-
-
Notifications
You must be signed in to change notification settings - Fork 735
Improve the discovery of the doc comment for symbol (or may be a symbol for a doc comment) #1752
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
Side note. In my custom fork, based on TypeDoc 0.17, i was using different heuristic for the function shouldBeIgnoredAsNotDocumented (node: ts.Declaration, kind: ReflectionKind): boolean {
// never ignore modules, global, and enum members
if (kind === ReflectionKind.Module || kind === ReflectionKind.Global || kind === ReflectionKind.EnumMember) {
return false;
}
// do not ignore properties of the object types, that has comment themselves, for example
//
// /**
// * has docs
// */
// export SomeType = { prop1 : string }
//
// same applies to the inline types for function arguments:
//
// function someFunc(arg1 : { prop1 : string, prop2 : number }) {...}
//
// The `prop1` from above should be included in the docs, even that it has no documentation
// Note, that this does not seem to apply to classes and interfaces - for those, even the class/interface
// has docs, we still want to exclude the undocumented properties
// Thankfully for object literals the kind of properties seems to be set to ReflectionKind.Variable
if (kind === ReflectionKind.Variable && hasCommentOnParentAxis(node)) {
return false;
}
const hasComment: boolean = Boolean(getRawComment(node));
return !hasComment;
}
function hasCommentOnParentAxis (node: ts.Node): boolean {
let currentNode: ts.Node = node;
while (currentNode) {
if (Boolean(getRawComment(currentNode))) { return true; }
currentNode = currentNode.parent;
}
return false;
} |
That definitely seems more like how it should work to me, I really dislike that reflections are used for object types in the first place, but haven't gotten around to it. We rely on ts.getLeadingCommentRanges to extract comments, I suspect that's not being returned for some reason... or maybe properties aren't included in the list of syntax kinds to search for that reflection type. |
Uh oh!
There was an error while loading. Please reload this page.
Search terms
Doc comment
Description
I'm using the
excludeNotDocumented
option to prevent symbols w/o documentation to appear in the docs.Sometimes I need to document in the inline object type, for example for function arguments:
The type of

options
argument appears as{}
in the docs (this is expected, because of theexcludeNotDocumented
):Now, to include them in the docs, I'm trying to provide a documentation for the properties:
The result, however, is the same:

To make it work, the doc comment needs to reside on the separate line, above the symbol:
This produces:

Expected
I'd expect, that the exact location of the doc comment should be not significant. Under "doc comment" I mean a comment with leading double star:
/** */
. The doc comment should just precede the symbol it documents, whether on the same line, or on the next line.Environment
The text was updated successfully, but these errors were encountered: