Markdown headings support
See original GitHub issueSupport for markdown headings is listed as a goal in the README, but unsupported in https://github.com/microsoft/tsdoc/issues/169. In practice (using the tsdoc playground) it seems to be unsupported. In #169, it is also recommended to open a new issue for further discussion on this point if needed.
To start the discussion, I will share this example that currently works well with TypeDoc:
/**
* Reverse an array in-place.
*
* @param array - The mutable array-like object of interest.
*
* @param start - The index of the first element in the range to be
* reversed, inclusive. The default value is `0`. Negative values
* are taken as an offset from the end of the array.
*
* @param stop - The index of the last element in the range to be
* reversed, inclusive. The default value is `-1`. Negative values
* are taken as an offset from the end of the array.
*
* #### Complexity
* Linear.
*
* #### Undefined Behavior
* A `start` or `stop` index which is non-integral.
*
* #### Example
* ```typescript
* import { ArrayExt } from '@lumino/algorithm';
*
* let data = [0, 1, 2, 3, 4];
* ArrayExt.reverse(data, 1, 3); // [0, 3, 2, 1, 4]
* ArrayExt.reverse(data, 3); // [0, 3, 2, 4, 1]
* ArrayExt.reverse(data); // [1, 4, 2, 3, 0]
* ```
*/
In this comment, the #### Example
heading can and should be replaced with @example
. It is not so clear what to do with the #### Complexity
and #### Undefined Behavior
headings. A logical first step is to put both in a @remarks
section, but it is unclear if there is any way to subdivide the remarks section further (without falling back to HTML), other than to allow markdown headers.
Issue Analytics
- State:
- Created 4 years ago
- Comments:8
Top GitHub Comments
There are different scenarios for different tools. The setup that I’m used to is like this:
Typically the original developer may never see the final rendered output at all. Even if there is a nice staging server stood up somewhere, the person writing the code may not be interested in that, and would not bother to look at it.
Thus wherever reasonable, it is desirable to catch mistakes as early in the pipeline as possible. Making TSDoc very strict and predictable enables us to catch issues by looking at code comments, without needing to run an entire documentation pipeline to understand how it will get rendered. For people who don’t have this requirement, these strict checks can easily be disabled.
I did not know that! Maybe TSDoc should start with
##
then, since the title is expected to be provided by the documentation system.Does anybody else have an issue with this? We could even issue a validation warning for
#
(or###
without##
).CC @rbuckton