From 9ab2e217e3d0a9d21554cfc6142963f0388841fc Mon Sep 17 00:00:00 2001 From: T-O-R-U-S Date: Mon, 14 Feb 2022 18:54:19 +0400 Subject: [PATCH] doc: make minor fixes to contributing guides PR-URL: https://github.com/nodejs/node/pull/41966 Reviewed-By: James M Snell Reviewed-By: Derek Lewis Reviewed-By: Antoine du Hamel Reviewed-By: Darshan Sen Reviewed-By: Matteo Collina Reviewed-By: Rich Trott --- .../maintaining-the-build-files.md | 10 +++--- .../maintaining-types-for-nodejs.md | 35 +++++++++++-------- 2 files changed, 27 insertions(+), 18 deletions(-) diff --git a/doc/contributing/maintaining-the-build-files.md b/doc/contributing/maintaining-the-build-files.md index 67c86281c63ed4..e1d3fa6e04969f 100644 --- a/doc/contributing/maintaining-the-build-files.md +++ b/doc/contributing/maintaining-the-build-files.md @@ -13,17 +13,17 @@ There are three main build files that may be directly run when building Node.js: create platform-dependent build files. Its output is usually in one of these formats: Makefile, MSbuild, ninja, or XCode project files (the main Makefile mentioned below is maintained separately by humans). For a detailed - guide on this script, see [configure](#configure). + guide on this script, see [configure][]. * `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a - subset of the targets available in the [Makefile](#makefile), and a few + subset of the targets available in the [Makefile][], and a few targets of its own. For a detailed guide on this script, see [vcbuild.bat](#vcbuildbat). * `Makefile`: A Makefile that can be run with GNU Make. It provides a set of targets that build and test the Node.js binary, produce releases and documentation, and interact with the CI to run benchmarks or tests. For a - detailed guide on this file, see [Makefile](#makefile). + detailed guide on this file, see [Makefile][]. -On Windows `vcbuild.bat` runs [configure](#configure) before building the +On Windows `vcbuild.bat` runs [configure][] before building the Node.js binary, on other systems `configure` must be run manually before running `make` on the `Makefile`. @@ -58,3 +58,5 @@ maintained by humans. This is not usually run on Windows, where of this option. [GYP]: https://gyp.gsrc.io/docs/UserDocumentation.md +[Makefile]: #makefile +[configure]: #configure diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 5cc52bd6ce931e..777405aa93f4cc 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -1,11 +1,10 @@ # Maintaining types for Node.js -While JavaScript is an untyped language, there are a number of complementary -technologies like [TypeScript](https://www.typescriptlang.org/) and -[Flow](https://flow.org/) which allow developers to use types within their -JavaScript projects. While many people don't use types, there are enough -who do that the project has agreed it's important to work towards having -[suitable types for end-users](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#suitable-types-for-end-users). +While JavaScript is a weakly-typed language, there are some complementary tools +like [TypeScript][] and [Flow][], which allow developers to annotate the source +code of their JavaScript projects. While many people don't annotate their code, +or make use of annotations at all, there are enough who do that the project has +agreed it's important to work towards having [suitable types for end-users][]. ## High level approach @@ -13,9 +12,8 @@ There are a number of ways that types could be maintained for Node.js ranging from shipping them with the Node.js runtime to having them be externally maintained. -The different options were discussed as part of the -[next-10](https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#suitable-types-for-end-users) -effort and it was agreed that maintaining them externally is the best approach. +The different options were discussed as part of the [next-10][] effort and it +was agreed that maintaining them externally is the best approach. Some of the advantages to this approach include: * Node.js maintainers do not need to be familiar with any given type @@ -34,22 +32,22 @@ The agreement was that the ideal flow would be as follows: When you run `make doc` the canonical markdown files used to document the Node.js APIs in the -[doc/api](https://github.com/nodejs/node/tree/master/doc/api) +[doc/api][] directory are converted to both an `.html` file and a `.json` file. As part of the regular build/release process both the `html` and -`json` files are published to [nodejs.org](https://nodejs.org/en/docs/). +`json` files are published to [nodejs.org][]. The generator that does the conversion is in the -[tools/doc](https://github.com/nodejs/node/tree/master/tools/doc) +[tools/doc][] directory. ## Markdown structure The constraints required on the markdown files in the -[doc/api](https://github.com/nodejs/node/tree/master/doc/api) directory +[doc/api][] directory in order to be able to generate the JSON files are defined in the -[documentation-style-guide](https://github.com/nodejs/node/blob/master/doc/README.md#documentation-style-guide). +[documentation-style-guide][]. ## Planned changes (as of Jan 1 2022) @@ -61,3 +59,12 @@ afterwards. There is an ongoing effort to add additional markdown constraints and then update the flow in order to be able to generate a better JSON output. + +[Flow]: https://flow.org/ +[TypeScript]: https://www.typescriptlang.org/ +[doc/api]: https://github.com/nodejs/node/tree/HEAD/doc/api +[documentation-style-guide]: https://github.com/nodejs/node/blob/HEAD/doc/README.md#documentation-style-guide +[next-10]: https://github.com/nodejs/next-10/blob/HEAD/meetings/summit-nov-2021.md#suitable-types-for-end-users +[nodejs.org]: https://nodejs.org/en/docs/ +[suitable types for end-users]: https://github.com/nodejs/node/blob/HEAD/doc/contributing/technical-priorities.md#suitable-types-for-end-users +[tools/doc]: https://github.com/nodejs/node/tree/HEAD/tools/doc