Customize the order of doc comment block tag rendering

[Oblarg]

Search Terms

block tags @remarks @example @param

Problem

Currently there seems to be no way to force the "parameters" block to render above the "examples" block. This is troublesome if the @example block is lengthy.

Suggested Solution

Add an option to mandate the rendering order (top-to-bottom) of the existing block tag sections. This could be represented by a simple string array.

[Gerrit0]

This is unimplementable given TypeDoc's current reflection architecture. Comments on parameters are not contained within the comment for the signature, but on each parameter.

That said, TypeDoc really should render the comment summary, then parameters + return type, then the remaining block tags, which would make this better.

[Oblarg]

If it's possible to change the default rendering order, why is it not possible to make that rendering order depend on some literal array in the global options?

[Gerrit0]

It's possible for everything except parameters + returns -- unless an incredible amount of hackery is done, the parameters and returns sections aren't kept in the same collection as the block tags.

[Gerrit0]

Changelog entry:

• When rendering functions/methods, TypeDoc will now render the comment summary above the parameters/return type,
  and any other block tags in the order they are defined in the comment, Customize the order of doc comment block tag rendering #2285.