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.

[ramitheeb]

@Gerrit0 anyway we can render examples above Parameters ?

[Gerrit0]

You could do it with a custom theme. There's no builtin support.

[Oblarg]

really glad to see this make it in - thanks!

[w10036w]

hi team, currently I am facing the annoying inconsistent disorder of the tags & type defs (see screenshots).
I cannot find any patterns as I have the similar format / order.
any ideas?
e.g.