diff options
author | isaacs <i@izs.me> | 2012-02-27 23:06:14 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2012-03-01 03:22:48 +0400 |
commit | d71f9944cc5bf485287442707bf31f0deb8b252b (patch) | |
tree | 8526dc4379008a8147f9dcdb3fdb9af16e7bd012 /doc/api | |
parent | f28d482cd43a2751f9a3efedf0ab0bce11fa7645 (diff) |
Add 'about these docs' section
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/_toc.markdown | 3 | ||||
-rw-r--r-- | doc/api/all.markdown | 1 | ||||
-rw-r--r-- | doc/api/documentation.markdown | 59 |
3 files changed, 61 insertions, 2 deletions
diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index ec37a578d28..4e671068eb6 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 8b5ae257d35..47a818f7bf0 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 00000000000..d3c7a869288 --- /dev/null +++ b/doc/api/documentation.markdown @@ -0,0 +1,59 @@ +# About this Documentation + +<!-- type=misc --> + +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 + +<!--type=misc--> + +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. |