diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index ec37a578d28e94..4e671068eb699b 100644 --- a/doc/api/_toc.markdown +++ b/doc/api/_toc.markdown @@ -1,5 +1,4 @@ -## Table of Contents - +* [About these Docs](documentation.html) * [Synopsis](synopsis.html) * [Globals](globals.html) * [STDIO](stdio.html) diff --git a/doc/api/all.markdown b/doc/api/all.markdown index 8b5ae257d35348..47a818f7bf0790 100644 --- a/doc/api/all.markdown +++ b/doc/api/all.markdown @@ -1,3 +1,4 @@ +@include documentation @include synopsis @include globals @include stdio diff --git a/doc/api/documentation.markdown b/doc/api/documentation.markdown new file mode 100644 index 00000000000000..d3c7a8692884bb --- /dev/null +++ b/doc/api/documentation.markdown @@ -0,0 +1,59 @@ +# About this Documentation + + + +The goal of this documentation is to comprehensively explain the Node.js +API, both from a reference as well as a conceptual point of view. Each +section describes a built-in module or high-level concept. + +Where appropriate, property types, method arguments, and the arguments +provided to event handlers are detailed in a list underneath the topic +heading. + +Every `.html` document has a corresponding `.json` document presenting +the same information in a structured manner. This feature is +experimental, and added for the benefit of IDEs and other utilities that +wish to do programmatic things with the documentation. + +Every `.html` and `.json` file is generated based on the corresponding +`.markdown` file in the `doc/api/` folder in node's source tree. The +documentation is generated using the `tools/doc/generate.js` program. +The HTML template is located at `doc/template.html`. + +## Stability Index + + + +Throughout the documentation, you will see indications of a section's +stability. The Node.js API is still somewhat changing, and as it +matures, certain parts are more reliable than others. Some are so +proven, and so relied upon, that they are unlikely to ever change at +all. Others are brand new and experimental, or known to be hazardous +and in the process of being redesigned. + +The notices look like this: + + Stability: 1 Experimental + +The stability indices are as follows: + +* **0 - Deprecated** This feature is known to be problematic, and changes are +planned. Do not rely on it. Use of the feature may cause warnings. Backwards +compatibility should not be expected. + +* **1 - Experimental** This feature was introduced recently, and may change +or be removed in future versions. Please try it out and provide feedback. +If it addresses a use-case that is important to you, tell the node core team. + +* **2 - Unstable** The API is in the process of settling, but has not yet had +sufficient real-world testing to be considered stable. Backwards-compatibility +will be maintained if reasonable. + +* **3 - Stable** The API has proven satisfactory, but cleanup in the underlying +code may cause minor changes. Backwards-compatibility is guaranteed. + +* **4 - API Frozen** This API has been tested extensively in production and is +unlikely to ever have to change. + +* **5 - Locked** Unless serious bugs are found, this code will not ever +change. Please do not suggest changes in this area; they will be refused.