Recognize more comment styles

[adrianheine]

Currently, since typedoc uses getJSDocCommentRanges for retrieving comments, line comments and block comments that don't start with /** are not recognized:

class X {
  /**
   * works
   */
  x() {
  }

  /*
   * doesn't work
   */
  x2() {
  }

  // doesn't work
  x3() {
  }
}

It should be fairly easy to remove this limitation by copying getJSDocCommentRanges without the filtering at the end.

[Gerrit0]

The JSDoc style of comments is pretty much standard for documenting code in the JS world, much like triple-slash comments are standard in the C# world.

Wouldn't this cause confusion when comments not intended to be used for documentation are picked up?

[adrianheine]

If you're worried about that, this could still be an option.

[aciccarello]

Thanks for the suggestion, however I agree with @Gerrit0 that we should only document comments explicitly designated with /**. Microsoft's tsdoc project follows a similar convention.

I'm going to close this for now but feel free to continue commenting.

[adrianheine]

Hm, that's a pretty arbitrary limitation you want to keep there.

[aciccarello]

The convention is supposed to give control over what comments show up in documentation. I consider it a fairly standard convention to use /** to mean "I want this documented".

For example, there may be situations like the following where you would want to leave a comment but not have that documented.

class Foo extends Bar {
  someProp: string;

  // Override parent props
  inheritedVal1 = true;
  inheritedVal2 = true;
}

Could you explain the use case for documenting other comments?

[adrianheine]

Yes, and I'm just asking for an option that supports all comment styles, disabled by default. My use case is https://github.com/codemirror/codemirror.next, in which we use line comments.

[aciccarello]

True, I agree that this would likely be disabled by default. However, I'm not sure that it is worth the extra complexity. Could you explain why you want to document line comments?

[adrianheine]

Because that's our comment style for all kinds of comments.

[svicalifornia]

I second this request.

[mattduggan]

Third - Would appreciate an option to specify the types of comments that end up in the documentation, e.g. 'single-line' | 'multi-line' | 'block', where the default is 'block'.

It's often the case that I want a single line comment for brevity.

enum Direction {
  /**
   * this
   */ 
  North,
  /**
   * is
   */ 
  East,
  /**
   * an
   */ 
  South,
  /**
   * example
   */ 
  West,
  /**
   * @deprecated
   */ 
  Left = West
}

vs

enum Direction {
  // this
  North,
  // is
  East,
  // an
  South,
  // example
  West,
  // @deprecated 
  Left = West
}

[Gerrit0]

You can still use /** style comments on a single line.

enum Direction {
  /** this */
  North,
  ...
}

[adrianheine]

btw, we've written https://github.com/adrianheine/gettypes/ and use that together with https://github.com/marijnh/builddocs. It's highly opinionated, though.