Discussion: Formatting inconsistency in markdown documentation

[KevinEady]

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

node-addon-api/doc/env.md

Lines 87 to 104 in b8525e2

	### SetInstanceData
	```cpp
	template <typename T> using Finalizer = void (*)(Env, T*);
	template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
	void SetInstanceData(T* data) const;
	```
	- `[template] fini`: A function to call when the instance data is to be deleted.
	Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
	not given, the default finalizer will be used, which simply uses the `delete`
	operator to destroy `T*` when the addon instance is unloaded.
	- `[in] data`: A pointer to data that will be associated with the instance of
	the addon for the duration of its lifecycle.
	Associates a data item stored at `T* data` with the current instance of the
	addon. The item will be passed to the function `fini` which gets called when an
	instance of the addon is unloaded.

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

node-addon-api/doc/addon.md

Lines 144 to 161 in b8525e2

	### DefineProperties
	Defines function, accessor, and/or value properties on an object using add-on
	instance methods.
	```cpp
	template <typename T>
	Napi::Object
	Napi::Addon<T>::DefineProperties(Napi::Object object,
	const std::initializer_list<PropertyDescriptor>& properties);
	```
	* `[in] object`: The object that will receive the new properties.
	* `[in] properties`: Initializer list of property descriptors of the methods,
	property accessors, and values to attach to `object`.
	See: [`Class property and descriptor`](class_property_descriptor.md).
	Returns `object`.

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]

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]

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]

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.