From 9a6399ca2c28cd81f0bda32549d6a69239c73d8f Mon Sep 17 00:00:00 2001 From: Jose Date: Fri, 2 Aug 2024 13:02:50 +0200 Subject: [PATCH 1/2] JavaScript doc comment fixes --- cpp/src/Slice/Parser.cpp | 10 +++++++-- cpp/src/Slice/Parser.h | 1 + cpp/src/slice2js/Gen.cpp | 38 +++++++++++++++++++++++++++++---- js/src/Ice/Connection.d.ts | 4 ++-- js/src/Ice/LocalExceptions.d.ts | 13 ++++++++--- js/src/Ice/ObjectAdapter.d.ts | 2 +- 6 files changed, 56 insertions(+), 12 deletions(-) diff --git a/cpp/src/Slice/Parser.cpp b/cpp/src/Slice/Parser.cpp index 28497a89a1d..1c0e0904a8d 100644 --- a/cpp/src/Slice/Parser.cpp +++ b/cpp/src/Slice/Parser.cpp @@ -732,6 +732,12 @@ namespace CommentPtr Slice::Contained::parseComment(bool stripMarkup) const +{ + return parseComment(_comment, stripMarkup); +} + +CommentPtr +Slice::Contained::parseComment(const string& text, bool stripMarkup) const { CommentPtr comment = make_shared(); @@ -745,7 +751,7 @@ Slice::Contained::parseComment(bool stripMarkup) const comment->_deprecated.push_back(IceInternal::trim(*reason)); } - if (!comment->_isDeprecated && _comment.empty()) + if (!comment->_isDeprecated && text.empty()) { return nullptr; } @@ -753,7 +759,7 @@ Slice::Contained::parseComment(bool stripMarkup) const // // Split up the comment into lines. // - StringList lines = splitComment(_comment, stripMarkup); + StringList lines = splitComment(text, stripMarkup); StringList::const_iterator i; for (i = lines.begin(); i != lines.end(); ++i) diff --git a/cpp/src/Slice/Parser.h b/cpp/src/Slice/Parser.h index f4b2ee36120..3be04cef327 100644 --- a/cpp/src/Slice/Parser.h +++ b/cpp/src/Slice/Parser.h @@ -380,6 +380,7 @@ namespace Slice std::string file() const; std::string line() const; std::string comment() const; + CommentPtr parseComment(const std::string&, bool) const; CommentPtr parseComment(bool) const; int includeLevel() const; diff --git a/cpp/src/slice2js/Gen.cpp b/cpp/src/slice2js/Gen.cpp index e50c0ac2602..c482a37cc44 100644 --- a/cpp/src/slice2js/Gen.cpp +++ b/cpp/src/slice2js/Gen.cpp @@ -22,6 +22,36 @@ using namespace IceInternal; namespace { + CommentPtr parseComment(const ContainedPtr& p) + { + string text = p->comment(); + const string linkBegin = "{@link "; + const string linkEnd = "}"; + + string::size_type pos = text.find(linkBegin); + while (pos != string::npos) + { + string::size_type endPos = text.find(linkEnd, pos); + if (endPos == string::npos) + { + // Invalid link, ignore it + break; + } + + string link = text.substr(pos + linkBegin.size(), endPos - pos - linkBegin.size()); + if (link.find("#") == 0) + { + link = link.substr(1); + } + const string replacement = "{@ link " + link + "}"; + + text.replace(pos, endPos - pos + linkEnd.size(), replacement); + pos = text.find(linkBegin, pos + replacement.size()); + } + + return p->parseComment(text, false); + } + // Convert a path to a module name, e.g., "../foo/bar/baz.ice" -> "__foo_bar_baz" string pathToModule(const string& path) { @@ -206,7 +236,7 @@ namespace return; } - CommentPtr doc = p->parseComment(false); + CommentPtr doc = parseComment(p); out << nl << "/**"; @@ -2519,7 +2549,7 @@ Slice::Gen::TypeScriptVisitor::visitClassDefStart(const ClassDefPtr& p) _out << nl << " * One-shot constructor to initialize all data members."; for (const auto& dataMember : allDataMembers) { - CommentPtr comment = dataMember->parseComment(false); + CommentPtr comment = parseComment(dataMember); if (comment) { _out << nl << " * @param " << fixId(dataMember->name()) << " " << getDocSentence(comment->overview()); @@ -2612,7 +2642,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p) } const string contextParam = escapeParam(paramList, "context"); - CommentPtr comment = op->parseComment(false); + CommentPtr comment = parseComment(op); const string contextDoc = "@param " + contextParam + " The Context map to send with the invocation."; const string asyncDoc = "The asynchronous result object for the invocation."; @@ -2715,7 +2745,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p) } const string currentParam = escapeParam(inParams, "current"); - CommentPtr comment = p->parseComment(false); + CommentPtr comment = parseComment(p); const string currentDoc = "@param " + currentParam + " The Current object for the invocation."; const string resultDoc = "The result or a promise like object that will " "be resolved with the result of the invocation."; diff --git a/js/src/Ice/Connection.d.ts b/js/src/Ice/Connection.d.ts index c5190c8c06b..dcfb0683dde 100644 --- a/js/src/Ice/Connection.d.ts +++ b/js/src/Ice/Connection.d.ts @@ -153,8 +153,8 @@ declare module "ice" { /** * Throw an exception indicating the reason for connection closure. For example, * {@link CloseConnectionException} is raised if the connection was closed gracefully, whereas - * {@link ConnectionManuallyClosedException} is raised if the connection was manually closed by - * the application. This operation does nothing if the connection is not yet closed. + * {@link ConnectionAbortedException}/{@link ConnectionClosedException} is raised if the connection was + * manually closed by the application. This operation does nothing if the connection is not yet closed. */ throwException(): void; } diff --git a/js/src/Ice/LocalExceptions.d.ts b/js/src/Ice/LocalExceptions.d.ts index 3abed7c66ac..87ea8ff442e 100644 --- a/js/src/Ice/LocalExceptions.d.ts +++ b/js/src/Ice/LocalExceptions.d.ts @@ -41,9 +41,8 @@ declare module "ice" { */ class UnknownException extends LocalException { /** - * One-shot constructor to initialize all data members. - * @param unknown This field is set to the textual representation of the unknown exception if available. - * @param ice_cause The error that cause this exception. + * Constructs an unknown exception. + * @param message The exception message. */ constructor(message: string); unknown: string; @@ -53,6 +52,10 @@ declare module "ice" { * The dispatch failed with a {@link LocalException} that is not one of the special marshal-able local exceptions. */ class UnknownLocalException extends UnknownException { + /** + * Constructs an unknown local exception. + * @param message The exception message. + */ constructor(message: string); } @@ -60,6 +63,10 @@ declare module "ice" { * The dispatch returned a {@link UserException} that was not declared in the operation's exception specification. */ class UnknownUserException extends UnknownException { + /** + * Constructs an unknown user exception. + * @param message The exception message. + */ constructor(message: string); } diff --git a/js/src/Ice/ObjectAdapter.d.ts b/js/src/Ice/ObjectAdapter.d.ts index d5f4a36b2cf..4b9e4302a74 100644 --- a/js/src/Ice/ObjectAdapter.d.ts +++ b/js/src/Ice/ObjectAdapter.d.ts @@ -97,7 +97,7 @@ declare module "ice" { /** * Install a middleware in this object adapter. * - * @param The middleware to install. + * @param middleware The middleware to install. * @return This object adapter. * @throws Error Thrown if the object adapter's dispatch pipeline has already been * created. This creation typically occurs the first time the object adapter dispatches an incoming request. From efae92899783fe3b09f531c1e051d0020f1ab0f6 Mon Sep 17 00:00:00 2001 From: Jose Date: Fri, 2 Aug 2024 16:38:42 +0200 Subject: [PATCH 2/2] JavaScript doc comment improvements --- cpp/src/slice2js/Gen.cpp | 30 +++++++++++------------------- js/package-lock.json | 34 ++++++++++++++++++++-------------- js/package.json | 8 ++++---- 3 files changed, 35 insertions(+), 37 deletions(-) diff --git a/cpp/src/slice2js/Gen.cpp b/cpp/src/slice2js/Gen.cpp index c482a37cc44..7550b4aa651 100644 --- a/cpp/src/slice2js/Gen.cpp +++ b/cpp/src/slice2js/Gen.cpp @@ -24,6 +24,8 @@ namespace { CommentPtr parseComment(const ContainedPtr& p) { + // JavaScript TypeDoc doc processor doesn't accept # at the beginning of a link + // so we need to remove it. string text = p->comment(); const string linkBegin = "{@link "; const string linkEnd = "}"; @@ -43,7 +45,7 @@ namespace { link = link.substr(1); } - const string replacement = "{@ link " + link + "}"; + const string replacement = "{@link " + link + "}"; text.replace(pos, endPos - pos + linkEnd.size(), replacement); pos = text.find(linkBegin, pos + replacement.size()); @@ -282,7 +284,6 @@ namespace const OperationPtr& op, const CommentPtr& doc, OpDocParamType type, - const StringList& preParams = StringList(), const StringList& postParams = StringList()) { ParamDeclList params; @@ -299,11 +300,6 @@ namespace break; } - if (!preParams.empty()) - { - writeDocLines(out, preParams, true); - } - map paramDoc = doc->parameters(); for (ParamDeclList::iterator p = params.begin(); p != params.end(); ++p) { @@ -333,9 +329,10 @@ namespace ExceptionPtr ex = op->container()->lookupException(name, false); if (ex) { - name = ex->scoped().substr(2); + name = ex->scoped(); } - out << nl << " * @throws " << name << " "; + name = JsGenerator::fixId(name); + out << nl << " * @throws {@link " << name << "} "; writeDocLines(out, p->second, false); } } @@ -345,8 +342,6 @@ namespace const OperationPtr& op, const CommentPtr& doc, OpDocParamType type, - bool showExceptions, - const StringList& preParams = StringList(), const StringList& postParams = StringList(), const StringList& returns = StringList()) { @@ -357,7 +352,7 @@ namespace writeDocLines(out, doc->overview(), true); } - writeOpDocParams(out, op, doc, type, preParams, postParams); + writeOpDocParams(out, op, doc, type, postParams); if (!returns.empty()) { @@ -365,10 +360,7 @@ namespace writeDocLines(out, returns, false); } - if (showExceptions) - { - writeOpDocExceptions(out, op, doc); - } + writeOpDocExceptions(out, op, doc); if (!doc->misc().empty()) { @@ -2652,7 +2644,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p) StringList postParams, returns; postParams.push_back(contextDoc); returns.push_back(asyncDoc); - writeOpDocSummary(_out, op, comment, OpDocInParams, false, StringList(), postParams, returns); + writeOpDocSummary(_out, op, comment, OpDocInParams, postParams, returns); } _out << nl << fixId(op->name()) << spar; for (const auto& param : inParams) @@ -2745,7 +2737,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p) } const string currentParam = escapeParam(inParams, "current"); - CommentPtr comment = parseComment(p); + CommentPtr comment = parseComment(op); const string currentDoc = "@param " + currentParam + " The Current object for the invocation."; const string resultDoc = "The result or a promise like object that will " "be resolved with the result of the invocation."; @@ -2754,7 +2746,7 @@ Slice::Gen::TypeScriptVisitor::visitInterfaceDefStart(const InterfaceDefPtr& p) StringList postParams, returns; postParams.push_back(currentDoc); returns.push_back(resultDoc); - writeOpDocSummary(_out, op, comment, OpDocInParams, false, StringList(), postParams, returns); + writeOpDocSummary(_out, op, comment, OpDocInParams, postParams, returns); } _out << nl << "abstract " << fixId(op->name()) << spar; for (const auto& param : inParams) diff --git a/js/package-lock.json b/js/package-lock.json index 50078e91447..de2d30a5ff9 100644 --- a/js/package-lock.json +++ b/js/package-lock.json @@ -9,7 +9,7 @@ "version": "3.8.0-alpha0", "license": "GPL-2.0", "devDependencies": { - "@types/node": "^20.14.2", + "@types/node": "^22.1.0", "del": "^7.1.0", "gulp": "^5.0.0", "gulp-ext-replace": "^0.3.0", @@ -17,10 +17,10 @@ "gulp-typescript": "^5.0.1", "http-server": "^14.1.1", "jshint": "^2.13.6", - "prettier": "^3.3.2", + "prettier": "^3.3.3", "pump": "^3.0.0", - "typedoc": "^0.26.3", - "typescript": "^5.5.3", + "typedoc": "^0.26.5", + "typescript": "^5.5.4", "typescript-formatter": "^7.2.2", "vinyl": "^3.0.0", "vinyl-paths": "^5.0.0" @@ -88,11 +88,13 @@ "license": "MIT" }, "node_modules/@types/node": { - "version": "20.14.2", + "version": "22.1.0", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.1.0.tgz", + "integrity": "sha512-AOmuRF0R2/5j1knA3c6G3HOk523Ga+l+ZXltX8SF1+5oqcXijjfTd8fY3XRZqSihEu9XhtQnKYLmkFaoxgsJHw==", "dev": true, "license": "MIT", "dependencies": { - "undici-types": "~5.26.4" + "undici-types": "~6.13.0" } }, "node_modules/aggregate-error": { @@ -2814,7 +2816,9 @@ } }, "node_modules/prettier": { - "version": "3.3.2", + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.3.3.tgz", + "integrity": "sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==", "dev": true, "license": "MIT", "bin": { @@ -3445,9 +3449,9 @@ } }, "node_modules/typedoc": { - "version": "0.26.3", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.3.tgz", - "integrity": "sha512-6d2Sw9disvvpdk4K7VNjKr5/3hzijtfQVHRthhDqJgnhMHy1wQz4yPMJVKXElvnZhFr0nkzo+GzjXDTRV5yLpg==", + "version": "0.26.5", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.5.tgz", + "integrity": "sha512-Vn9YKdjKtDZqSk+by7beZ+xzkkr8T8CYoiasqyt4TTRFy5+UHzL/mF/o4wGBjRF+rlWQHDb0t6xCpA3JNL5phg==", "dev": true, "license": "Apache-2.0", "dependencies": { @@ -3494,9 +3498,9 @@ } }, "node_modules/typescript": { - "version": "5.5.3", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.3.tgz", - "integrity": "sha512-/hreyEujaB0w76zKo6717l3L0o/qEUtRgdvUBvlkhoWeOVMjMuHNHk0BRBzikzuGDqNmPQbg5ifMEqsHLiIUcQ==", + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.4.tgz", + "integrity": "sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==", "dev": true, "license": "Apache-2.0", "bin": { @@ -3563,7 +3567,9 @@ } }, "node_modules/undici-types": { - "version": "5.26.5", + "version": "6.13.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.13.0.tgz", + "integrity": "sha512-xtFJHudx8S2DSoujjMd1WeWvn7KKWFRESZTMeL1RptAYERu29D6jphMjjY+vn96jvN3kVPDNxU/E13VTaXj6jg==", "dev": true, "license": "MIT" }, diff --git a/js/package.json b/js/package.json index 04f4f8350d4..7cb093feeba 100644 --- a/js/package.json +++ b/js/package.json @@ -18,7 +18,7 @@ "types": "src/index.d.ts", "browserslist": "> 0.25%, not dead", "devDependencies": { - "@types/node": "^20.14.2", + "@types/node": "^22.1.0", "del": "^7.1.0", "gulp": "^5.0.0", "gulp-ext-replace": "^0.3.0", @@ -26,10 +26,10 @@ "gulp-typescript": "^5.0.1", "http-server": "^14.1.1", "jshint": "^2.13.6", - "prettier": "^3.3.2", + "prettier": "^3.3.3", "pump": "^3.0.0", - "typedoc": "^0.26.3", - "typescript": "^5.5.3", + "typedoc": "^0.26.5", + "typescript": "^5.5.4", "typescript-formatter": "^7.2.2", "vinyl": "^3.0.0", "vinyl-paths": "^5.0.0"