Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: document goal to have examples #42274

Closed
wants to merge 4 commits into from
Closed

doc: document goal to have examples #42274

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fd80dbc
doc: document goal to have examples
mhdawson Mar 9, 2022
2bee87c
squash: address comments
mhdawson Mar 10, 2022
6196cfc
Update doc/README.md
mhdawson Mar 14, 2022
25a012a
Update doc/README.md
mhdawson Mar 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions tools/doc/README.md
View file
Open in desktop
Expand Up @@ -106,3 +106,5 @@ This event is emitted on instances of `SomeClass`, not on the module itself.
* Methods have (list of arguments, returned value if defined, description).
* Modules have (description, Properties, Functions, Classes, Examples).
* Properties have (type, description).

Every Function and Method should have an in-line example showing their use.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if this is the best location to document goals. Also, I think this might be too broad.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tniessen I looked at either this doc or https://github.com/nodejs/node/tree/master/doc and this felt was the better of the 2. I agree neither is a great fit. Another option might be to add a maintaining-api-docs.md guide in https://github.com/nodejs/node/tree/master/doc/contributing. Do you have any other suggestions?

When you say too broad, do you mean that having an in-line example for every function and method does not make sense or that the description needs to be more specific in some way?

Copy link
Member

@Trott Trott Mar 9, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Every Function and Method should have an in-line example showing their use.
Every function should have a usage example.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When you say too broad, do you mean that having an in-line example for every function and method does not make sense or that the description needs to be more specific in some way?

I think it does not make sense in all cases, for example, when a class has many methods that aren't particularly helpful on their own, but only when used together. But since the PR has changed to restrict its scope to functions, I don't have a strong opinion on this.