typedoc: Top level module level comments don't show if imports exist

With 0.15.6 (should be out later today) TypeDoc supports the @packageDocumentation tag to mark a comment as documentation for the file. This is consistent with TSDoc’s effort to standardize blocks.

The legacy behavior of using a dummy comment still works, but using @packageDocumentation is preferred.

I sympathize with limitations of TS under the covers. However a full featured API documentation tool like TypeDoc should consider top level module documentation as a first-class feature one way or another.

I’ve seen far too many APIs documented that just dump you into a haphazard collection of exported symbols. The top-level documentation provides context to tie it all together and helps the reader make sense of what follows.

If I can be of any assistance I’m happy to help.

I’m not sure what the intention is behind the code, but this is due to these lines: https://github.com/TypeStrong/typedoc/blob/v0.9.0/src/lib/converter/factories/comment.ts#L90-L93

For people who end up here via search…

The module-level comment will only work if the first declaration also has a TSDoc comment. https://github.com/microsoft/FluidFramework/wiki/TSDoc-Guidelines#documenting-modules

There is a conflict between TypeDoc and TSDoc: https://github.com/matrix-org/matrix-js-sdk/issues/3243#issuecomment-1684411422

And adding support for an @module tag would be good https://github.com/microsoft/tsdoc/issues/296#issuecomment-898566841

@Gerrit0 Thanks for pointing out the TypeScript parsing.

This is a difficult problem to solve without breaking changes. There are many different cases we would need to handle if we were trying not to be too restrictive. The simplest semantics I can think of is that file documentation would need to be at the very beginning of the file and be followed by a empty line. Another option would be to require something like a @file comment tag, though I don’t love that idea.

I’d like to see some clarification on Microsoft/tsdoc#6 before making a breaking change.

File with imports

/**
 * This clearly is at the top of the file. Imports are never documented.
 */
import foo from 'foo';

export function bar() {
  foo();
}

File comment that isn’t first line

/*
 * Corporate header
 * @copyright Foo Inc.
 */
/**
 * I'm not sure how important this use case is but it may be worth recognizing.
 */

export function bar() {
  foo();
}

File without imports

/**
 * The only indication that this is a file level comment is the empty line.
 */

export function foo() {
  return 'foo';
}

export function bar() {
  return 'bar';
}

Commented out lines

/**
 * This clearly is at the top of the file. Imports are never documented.
 */
// import foo from 'foo';

export function bar() {
  // foo();
}

/**
 * This could have been a comment for the following line that was commented out.
 */
// const foo = () => 'foo';

export function bar() {
  foo();
}

//imports won’t be caught as a documentation comment. Change it to /** imports */ and you should be golden.

I am encountering the same issue. I also use the workaround described above (using a dummy doc comment). It would be nice if the lines highlighted by @christopherthielen were either removed or explained.

Yes, that did make it appear.

I’m curious if it thinks the comment is for the import.

Does the module comment appear if you do the following?

/**
* @copyright <our copyright here>
*/

/** ignore this comment */
import * as _ from "lodash";