search

nodejs / node-addon-api

Module for using Node-API from C++
MIT License
2.17k stars 459 forks source link

Discussion: Formatting inconsistency in markdown documentation #1530

Open KevinEady opened 4 months ago

KevinEady commented 4 months ago

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 commented 4 months ago

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] commented 1 month ago

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.

Furqan-Nadir commented 1 week ago

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.