Handling multiple comments per symbol

[Gerrit0]

TypeScript allows multiple comments to be attached to a symbol. Consider:

/** Comment one **/
enum A { a }
/** Comment two **/
enum A { b = 1 }

This presents a problem for documentation generators parsing the comments as they must either pick one of the comments, or take both comments and combine them. I believe tsdoc should either provide a function to merge comments, or should provide guidance on how to choose the comment to keep.

For reference, TypeDoc supports an @preferred tag which tells the generator which comment to use. If no @preferred tag is present, it will take the longest comment. VSCode (ts language service?) appears to simply concatenate any comment summaries and lists any @remarks blocks separately.

Related to the above, it might be worth standardizing what should happen if multiple comments are attached to a node, for example:

/** Comment one **/
/** Comment two **/
enum A { a }

In TypeDoc, only comment two would be used to document A. However, in VSCode, I again see that the summaries have been joined.

I understand this isn't directly related to the parsing of an actual comment, which is tsdoc's focus. However, it is a closely related issue which would benefit from a standard.

[Gerrit0]

I just realized, this is at least very closely related to #6, more probably a duplicate, but I'll leave that choice to the maintainers.

[octogonz]

Is there ever a legitimate reason to have two TDoc comments for the same API item? In your example, I'm thinking that /** Comment two */ should be used, and /** Comment one */ should be ignored, or perhaps the tool should issue a warning.

Consider this somewhat common practice for example:

/**
 * Copyright (c) 2018, ACME, Inc.
 */

/**
 * States of a check box
 */
enum CheckBoxState {
  Unchecked,
  Indeterminate,
  Checked
}

We definitely don't want "Copyright (c) 2018, ACME, Inc." to get merged into the documentation for the enum.

[octogonz]

I just realized, this is at least very closely related to #6, more probably a duplicate, but I'll leave that choice to the maintainers.

@Gerrit0 These contributions are very helpful. I'm almost done integrating the TSDoc library into API Extractor, at which point it will be considered "feature complete". Then I will collect all the ideas from the GitHub issues and write up a first draft of the spec document.

[Gerrit0]

Is there ever a legitimate reason to have two TDoc comments for the same API item?

I don't believe there is, I've always found the compiler's behavior confusing. However, for enums it might be accidentally added if the enum is separated into multiple declarations.

[octogonz]

Declaration merging is a more interesting case. However my opinion is that the documentation tool should somehow enforce that there is only one doc comment. Trying to merge doc comments seems complex and counterintuitive.

For example, API Extractor requires that either the property setter or the property getter should have a doc comment, but not both. The same policy would make sense for an enum with multiple declarations.

We initially took the same approach for overloaded functions, but for that special case there seems to be a general consensus that each overload should get its own doc comment. (Otherwise the @param entries can get messy.)