Discussion: Formatting inconsistency in markdown documentation

[KevinEady]

Some documented methods have the C++ definition before the description:

https://github.com/nodejs/node-addon-api/blob/b8525e2f8ca8887c5ec864706c27b8872a5a6256/doc/env.md?plain=1#L87-L104

... while others have the description before the C++ definition:

https://github.com/nodejs/node-addon-api/blob/b8525e2f8ca8887c5ec864706c27b8872a5a6256/doc/addon.md?plain=1#L144-L161

For some rough stats, it seems to be split almost evenly... Searching for ### .+\n+``` (ie. definition first) gives 208 results, while ### .+\n+\w (ie. description first) gives 219 results.

Do we have a preference? Does it matter?

[mhdawson]

We should check the Node.js api docs in nodejs/node/doc/api to see which it does and likely follow that.

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[Bucksmon]

Personally, I would prefer having documentation above the definition specifically because having a context on what you are reading makes it easier to understand and analyze.

[github-actions[bot]]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.