Skip to content

Discussion: Formatting inconsistency in markdown documentation #1530

Not planned
@KevinEady

Description

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?

Activity

mhdawson

mhdawson commented on Jul 5, 2024

@mhdawson
Member

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

github-actions

github-actions commented on Oct 4, 2024

@github-actions
Contributor

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

Furqan-Nadir commented on Oct 25, 2024

@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

github-actions commented on Jan 24, 2025

@github-actions
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

      Participants

      @KevinEady@mhdawson@Furqan-Nadir

      Issue actions

        Discussion: Formatting inconsistency in markdown documentation · Issue #1530 · nodejs/node-addon-api