From fd80dbc249da7b4312e2ea6e406d8b6a9bcf8cac Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 9 Mar 2022 17:33:20 -0500 Subject: [PATCH 1/4] doc: document goal to have examples As discussed in next-10 mini-summit on documentation see minutes where next steps were discussed - https://github.com/nodejs/next-10/blob/main/meetings/2022-02-16.md and minutes from summit - https://github.com/nodejs/next-10/blob/main/meetings/2022-02-16.md Signed-off-by: Michael Dawson --- tools/doc/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tools/doc/README.md b/tools/doc/README.md index e2aedfb1b56622..48bbcee9371499 100644 --- a/tools/doc/README.md +++ b/tools/doc/README.md @@ -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. From 2bee87cf2dcd095000765e3a37b99c4f37b29eec Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 10 Mar 2022 09:16:48 -0500 Subject: [PATCH 2/4] squash: address comments Signed-off-by: Michael Dawson --- doc/README.md | 1 + tools/doc/README.md | 2 -- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/README.md b/doc/README.md index a0f050ecd5cfc8..e59e175ba5bf59 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,6 +35,7 @@ this guide. (`[a link](http://example.com)`). * When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API. +* When documenting APIs, every function should have a usage example. * For code blocks: * Use [language][]-aware fences. (\`\`\`js) diff --git a/tools/doc/README.md b/tools/doc/README.md index 48bbcee9371499..e2aedfb1b56622 100644 --- a/tools/doc/README.md +++ b/tools/doc/README.md @@ -106,5 +106,3 @@ 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. From 6196cfc4ef655efc4b82db3f1b554663ae55bd8d Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 14 Mar 2022 18:00:34 -0400 Subject: [PATCH 3/4] Update doc/README.md --- doc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index e59e175ba5bf59..ec3eb6ffdde821 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,7 +35,7 @@ this guide. (`[a link](http://example.com)`). * When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API. -* When documenting APIs, every function should have a usage example. +* When documenting APIs, every function should have a usage example or link to an example that uses the function. * For code blocks: * Use [language][]-aware fences. (\`\`\`js) From 25a012afcf93ab13cb72d86a07704aaa65151a5a Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 14 Mar 2022 18:07:39 -0400 Subject: [PATCH 4/4] Update doc/README.md --- doc/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index ec3eb6ffdde821..3d8ad6246839e6 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,7 +35,8 @@ this guide. (`[a link](http://example.com)`). * When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API. -* When documenting APIs, every function should have a usage example or link to an example that uses the function. +* When documenting APIs, every function should have a usage example or + link to an example that uses the function. * For code blocks: * Use [language][]-aware fences. (\`\`\`js)