Skip to content

Commit

Permalink
Cleanup Javascript Doc Comment Generation (#3086)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pepone
pepone authored Nov 7, 2024
1 parent 414dca5 commit 7552a60
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 110 deletions.
6 changes: 3 additions & 3 deletions cpp/src/Slice/Parser.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -754,15 +754,15 @@ namespace
CommentPtr
Slice::Contained::parseComment(function<string(string, string)> linkFormatter, bool stripMarkup) const
{
CommentPtr comment = make_shared<Comment>();

// Split the comment's raw text up into lines.
StringList lines = splitComment(_comment, std::move(linkFormatter), stripMarkup);
if (lines.empty() && !comment->_isDeprecated)
if (lines.empty())
{
return nullptr;
}

CommentPtr comment = make_shared<Comment>();

// Parse the comment's text.
StringList::const_iterator i;
for (i = lines.begin(); i != lines.end(); ++i)
Expand Down
144 changes: 37 additions & 107 deletions cpp/src/slice2js/Gen.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -219,50 +219,6 @@ namespace
return ostr.str();
}

void writeDocSummary(Output& out, const ContainedPtr& p, bool includeDeprecated = true)
{
if (p->comment().empty())
{
return;
}

CommentPtr doc = p->parseComment(jsLinkFormatter);

out << nl << "/**";

if (!doc->overview().empty())
{
writeDocLines(out, doc->overview(), true);
}

if (!doc->misc().empty())
{
writeDocLines(out, doc->misc(), true);
}

if (!doc->seeAlso().empty())
{
writeSeeAlso(out, doc->seeAlso());
}

if (includeDeprecated)
{
if (!doc->deprecated().empty())
{
out << nl << " *";
out << nl << " * @deprecated ";
writeDocLines(out, doc->deprecated(), false);
}
else if (doc->isDeprecated())
{
out << nl << " *";
out << nl << " * @deprecated";
}
}

out << nl << " */";
}

enum OpDocParamType
{
OpDocInParams,
Expand Down Expand Up @@ -501,72 +457,46 @@ Slice::JsVisitor::writeConstantValue(
void
Slice::JsVisitor::writeDocCommentFor(const ContainedPtr& p, bool includeDeprecated)
{
StringList lines;

assert(!dynamic_pointer_cast<Operation>(p));
CommentPtr comment = p->parseComment(jsLinkFormatter);
if (!comment)
{
string comment = p->comment();
string::size_type pos = 0;
string::size_type nextPos;
string line;
while ((nextPos = comment.find_first_of('\n', pos)) != string::npos)
{
line = string(comment, pos, nextPos - pos);
pos = line.find_first_not_of(" \t");
if (pos != string::npos)
{
line = line.substr(pos);
}
lines.push_back(line);
pos = nextPos + 1;
}

line = string(comment, pos);
pos = line.find_first_not_of(" \t");
if (pos != string::npos)
{
line = line.substr(pos);
}

if (line.find_first_not_of(" \t\n\r") != string::npos)
{
lines.push_back(line);
}
// There's nothing to write for this doc-comment.
return;
}

// TODO this whole function seems bogus. Why do we manually split the lines and also call `parseComment`?
CommentPtr dc = p->parseComment(jsLinkFormatter);
_out << nl << "/**";

if (lines.empty())
if (!comment->overview().empty())
{
// There's nothing to write for this doc-comment.
return;
writeDocLines(_out, comment->overview(), true);
}

_out << nl << "/**";
if (!comment->misc().empty())
{
writeDocLines(_out, comment->misc(), true);
}

for (const auto& line : lines)
if (!comment->seeAlso().empty())
{
//
// @param must precede @returns, so emit any extra parameter
// when @returns is seen.
//
if (line.empty())
{
_out << nl << " *";
}
else
{
_out << nl << " * " << line;
}
writeSeeAlso(_out, comment->seeAlso());
}

if (includeDeprecated && dc && dc->isDeprecated())
// JavaScript doesn't provide a way to deprecate elements other than by using a comment, so we map both the Slice
// @deprecated tag and the deprecated metadata argument to a `@deprecated` JSDoc tag.
if (includeDeprecated && (comment->isDeprecated() || p->isDeprecated()))
{
_out << nl << " * @deprecated";
if (!dc->deprecated().empty())
// If a reason was supplied, append it after the `@deprecated` tag. If no reason was supplied, fallback to
// the deprecated metadata argument.
if (!comment->deprecated().empty())
{
// If a reason was supplied, append it after the `@deprecated` tag.
writeDocLines(_out, dc->deprecated(), false);
_out << " ";
writeDocLines(_out, comment->deprecated(), false);
}
else if (auto deprecated = p->getDeprecationReason())
{
_out << " " << *deprecated;
}
}

Expand Down Expand Up @@ -2424,7 +2354,7 @@ Slice::Gen::TypeScriptVisitor::visitClassDefStart(const ClassDefPtr& p)
const DataMemberList dataMembers = p->dataMembers();
const DataMemberList allDataMembers = p->allDataMembers();
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export class " << fixId(p->name()) << " extends ";
ClassDefPtr base = p->base();
if (base)
Expand Down Expand Up @@ -2455,7 +2385,7 @@ Slice::Gen::TypeScriptVisitor::visitClassDefStart(const ClassDefPtr& p)
for (const auto& dataMember : dataMembers)
{
_out << sp;
writeDocSummary(_out, dataMember);
writeDocCommentFor(dataMember);
_out << nl << fixDataMemberName(dataMember->name(), false, false) << ": "
<< typeToTsString(dataMember->type(), true) << ";";
}
Expand Down Expand Up @@ -2593,7 +2523,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p)
//
const string prx = p->name() + "Prx";
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export class " << prx << " extends " << _iceImportPrefix << "Ice.ObjectPrx";
_out << sb;

Expand Down Expand Up @@ -2717,7 +2647,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p)
_out << eb;

_out << sp;
writeDocSummary(_out, p, false);
writeDocCommentFor(p, false);
_out << nl << "export abstract class " << fixId(p->name()) << " extends " << _iceImportPrefix << "Ice.Object";
_out << sb;
for (const auto& op : p->allOperations())
Expand Down Expand Up @@ -2817,7 +2747,7 @@ Slice::Gen::TypeScriptVisitor::visitExceptionStart(const ExceptionPtr& p)
}

_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export class " << name << " extends " << baseRef << sb;
if (!allDataMembers.empty())
{
Expand Down Expand Up @@ -2855,7 +2785,7 @@ Slice::Gen::TypeScriptVisitor::visitStructStart(const StructPtr& p)
const string name = fixId(p->name());
const DataMemberList dataMembers = p->dataMembers();
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export class " << name << sb;
_out << nl << "constructor" << spar;
for (const auto& dataMember : dataMembers)
Expand Down Expand Up @@ -2932,7 +2862,7 @@ Slice::Gen::TypeScriptVisitor::visitSequence(const SequencePtr& p)
{
const string name = fixId(p->name());
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export type " << name << " = " << typeToTsString(p) << ";";

_out << sp;
Expand Down Expand Up @@ -2967,7 +2897,7 @@ Slice::Gen::TypeScriptVisitor::visitDictionary(const DictionaryPtr& p)
{
const string name = fixId(p->name());
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
string dictionaryType = typeToTsString(p);
if (dictionaryType.find("Ice.") == 0)
{
Expand Down Expand Up @@ -3008,13 +2938,13 @@ void
Slice::Gen::TypeScriptVisitor::visitEnum(const EnumPtr& p)
{
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export class " << fixId(p->name()) << " extends " << _iceImportPrefix << "Ice.EnumBase";
_out << sb;
for (const auto& enumerator : p->enumerators())
{
_out << sp;
writeDocSummary(_out, enumerator);
writeDocCommentFor(enumerator);
_out << nl << "static readonly " << fixId(enumerator->name()) << ": " << fixId(p->name()) << ";";
}
_out << nl;
Expand All @@ -3032,6 +2962,6 @@ void
Slice::Gen::TypeScriptVisitor::visitConst(const ConstPtr& p)
{
_out << sp;
writeDocSummary(_out, p);
writeDocCommentFor(p);
_out << nl << "export const " << fixId(p->name()) << ": " << typeToTsString(p->type()) << ";";
}

0 comments on commit 7552a60

Please sign in to comment.