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

[nickzelei]

It seems that top level module level comments don't appear if the module also has imports.

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

import * as _ from "lodash";

I have tested this in files that do have imports vs files that don't. The top level module comment only appears in modules that do not have any external imports.

[aciccarello]

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";

[nickzelei]

Yes, that did make it appear.

[nickzelei]

It only appeared when using the multi-line notation. It did not change when using single line.

[chriskrycho]

At least for me, it works if using a single-line comment in front of the imports.

[christopherthielen]

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

[nickzelei]

That looks like the culprit. Single-line comments are not ideal (at least for us) since they are used as file headers..so they are naturally multi-line.

Any comment type should be supported.

[demurgos]

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.

[ShawnTalbert]

I'm trying out TypeDoc and can't seem to get a top level module description to render.

The top of my module file looks like so:

/**
 * Document all the things
 */


//imports
import {Result} from "N/search"

Any ideas? I think this is a great project but if I can't have introductory text at the top of a module if feels rather raw.

[Gerrit0]

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

[ShawnTalbert]

Thanks @Gerrit0 switching to that style of comment (specifically with two prefix asterisks) worked. This is a very annoying bug.

[Gerrit0]

It is not a bug. TypeScript doesn't have the concept of a "module" documentation comment, and will take the concatenation of all doc comments before a declaration.

Given the following file:

/** Module */

/** Function */
export function test () {}

TypeScript will give "Module Function" as the documentation for test.

TypeDoc follows the JSDoc behavior of only treating the last comment as the documentation, so only "Function" would be included in the documentation. This makes it possible for a module comment to exist - if it is separated from any node by another documentation comment. This behavior is documented on the site.

While we could introduce a bunch of checks to say that some node types "can't" be documented, this would open the door to more breaking changes in the future, and I don't think it's a good idea right now.

[aciccarello]

@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();
}

[ShawnTalbert]

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.

[Gerrit0]

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.

[Rigii]

For me still an actual issue.
TypeDoc totally ignores top-level comments in my functional component index file.
Any imports here.
Same story if comment in a component file, and doc generates directly for it. I just started to use TypeDoc for my React project, could somebody explain what's wrong?
index.ts

/**
 * @module LogoSafeComponent
 * # This is a comment!!!
 * ## This is a comment 2!!!
 * ## This is a comment 3!!!
 * @param classNameCustom - custom styling class name
 * @param isSmall - img size
 * @module
 */

/** ignore this comment */
export * from "./LogoSafe"; 

modules.md output

[safe-app](README.md) / Exports

# some-app

## Table of contents

### Functions

- [LogoSafeComponent](modules.md#logosafecomponent)

## Functions

### LogoSafeComponent

▸ **LogoSafeComponent**(`__namedParameters`): `ReactElement`<`any`, `string` \| `JSXElementConstructor`<`any`\>\>

#### Parameters

| Name                                 | Type      |
| :----------------------------------- | :-------- |
| `__namedParameters`                  | `Object`  |
| `__namedParameters.classNameCustom?` | `string`  |
| `__namedParameters.isSmall?`         | `boolean` |

#### Returns

`ReactElement`<`any`, `string` \| `JSXElementConstructor`<`any`\>\>

#### Defined in

[LogoSafe.tsx:13](https://github.com/SomeAppOfficial/chrome-extension/blob/efc774c/src/components/LogoSafe/LogoSafe.tsx#L13)

If I highlit my component in code, the documentation looks as expected. Actually, I expect the same data in my .md output:

[Gerrit0]

Please open a new issue rather than bumping a (at this point very old) one

[heyakyra]

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: matrix-org/matrix-js-sdk#3243 (comment)

And adding support for an @module tag would be good microsoft/tsdoc#296 (comment)