Natural Docs

Last updated
Natural Docs
Original author(s) Greg Valure
Stable release
2.3 / September 11, 2023
Repository
Written in C# (Perl before 2.0) [1]
Operating system Cross-platform
Type Documentation generator
License AGPL
Website NaturalDocs.org

Natural Docs is a multi-language documentation generator. It is written in C# and available as free software under the terms of the AGPL. It attempts to keep the comments written in source code just as readable as the generated documentation. It is written and maintained by Greg Valure.

Contents

Background

Theoretically, Natural Docs can generate documentation from any language that can support comments, or from plain text files. When executed, it can automatically document functions, variables, classes, and inheritance from ActionScript, C#, and Perl regardless of existing documentation in the source code. In all other languages, these need to be explicitly documented for them to be generated. It can generate documentation in HTML, either with frames or without.

Unlike Javadoc, it is not considered an industry standard for documenting in any language, although it can incorporate Javadoc documentation for languages with "full support." [2] It is used by some hobbyists and companies, such as CNET Networks, Inc. and Iron Realms Entertainment. [3] [4] It has gained popularity amongst ActionScript developers because no other free documentation generator exists that fully supports ActionScript and because it generates higher-quality output than similar generators that partially support the language, such as ROBODoc.

Example

This is an example of the documentation style:

/*  * Function: Multiply  *   * Multiplies two integers.  *  * Parameters:  *    x - The first integer.  *    y - The second integer.  *  * Returns:  *    The two integers multiplied together.  *  * See Also:  *    <Divide>  */intMultiply(intx,inty){returnx*y;}

For comparison, this is how the same thing would be documented with Javadoc:

/**     * Multiplies two integers.     *     * @param x The first integer.     * @param y The second integer.     * @return The two integers multiplied together.     * @see Divide     */intMultiply(intx,inty){returnx*y;}

See also

Notes and references

Further reading

Related Research Articles

GNU Bison, commonly known as Bison, is a parser generator that is part of the GNU Project. Bison reads a specification in Bison syntax, warns about any parsing ambiguities, and generates a parser that reads sequences of tokens and decides whether the sequence conforms to the syntax specified by the grammar.

Type inference, sometimes called type reconstruction, refers to the automatic detection of the type of an expression in a formal language. These include programming languages and mathematical type systems, but also natural languages in some branches of computer science and linguistics.

<span class="mw-page-title-main">Doxygen</span> Free software for generating software documentation from source code

Doxygen is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxygen uses its parse tree to generate diagrams and charts of the code structure. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

In computer programming, a function object is a construct allowing an object to be invoked or called as if it were an ordinary function, usually with the same syntax. In some languages, particularly C++, function objects are often called functors.

In computer science, a generator is a routine that can be used to control the iteration behaviour of a loop. All generators are also iterators. A generator is very similar to a function that returns an array, in that a generator has parameters, can be called, and generates a sequence of values. However, instead of building an array containing all the values and returning them all at once, a generator yields the values one at a time, which requires less memory and allows the caller to get started processing the first few values immediately. In short, a generator looks like a function but behaves like an iterator.

ROBODoc is a documentation tool similar to Javadoc and licensed under the GPL. It is used to extract API documentation from source code. It can be used with any language that supports comments and works by extracting specially formatted headers. These are then reformatted into HTML, DocBook, TROFF, ASCII, LaTeX, PDF, or RTF.

reStructuredText is a file format for textual data used primarily in the Python programming language community for technical documentation.

Javadoc is a documentation generator created by Sun Microsystems for the Java language for generating API documentation in HTML format from Java source code. The HTML format is used for adding the convenience of being able to hyperlink related documents together.

PHPDoc is an adaptation of Javadoc format for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized. It allows external document generators like phpDocumentor, which is the de facto standard implementation, to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.

The Java Modeling Language (JML) is a specification language for Java programs, using Hoare style pre- and postconditions and invariants, that follows the design by contract paradigm. Specifications are written as Java annotation comments to the source files, which hence can be compiled with any Java compiler.

HeaderDoc is a documentation generator developed and maintained by Apple Inc. Using specially commented source code files as input, HeaderDoc generates documentation for the code in HTML or XML format. Syntax for HeaderDoc comment tags is largely similar to, and as of HeaderDoc version 8, supportive of Javadoc tags. HeaderDoc 8.7 and later also provides partial support for many Doxygen tags. Apple's HeaderDoc project is free, open source software distributed under the Apple Public Source License.

<span class="mw-page-title-main">Python syntax and semantics</span> Set of rules defining correctly structured programs

The syntax of the Python programming language is the set of rules that defines how a Python program will be written and interpreted. The Python language has many similarities to Perl, C, and Java. However, there are some definite differences between the languages. It supports multiple programming paradigms, including structured, object-oriented programming, and functional programming, and boasts a dynamic type system and automatic memory management.

Sandcastle is a documentation generator from Microsoft. It automatically produces MSDN-style code documentation out of reflection information of .NET assemblies and XML documentation comments found in the source code of these assemblies. It can also be used to produce user documentation from Microsoft Assistance Markup Language (MAML) with the same look and feel as reference documentation.

<span class="mw-page-title-main">NDoc</span>

NDoc is a code documentation generator for the Common Language Infrastructure created by Jason Diamond, Jean-Claude Manoli and Kral Ferch. It is licensed under the GNU General Public License.

In computer programming, an anonymous function is a function definition that is not bound to an identifier. Anonymous functions are often arguments being passed to higher-order functions or used for constructing the result of a higher-order function that needs to return a function. If the function is only used once, or a limited number of times, an anonymous function may be syntactically lighter than using a named function. Anonymous functions are ubiquitous in functional programming languages and other languages with first-class functions, where they fulfil the same role for the function type as literals do for other data types.

<span class="mw-page-title-main">Comment (computer programming)</span> Explanatory note in the source code of a computer program

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

This article describes the syntax of the C# programming language. The features described are compatible with .NET Framework and Mono.

In programming, a docblock or DocBlock is a specially formatted comment specified in source code that is used to document a specific segment of code. This makes the DocBlock format independent of the target language ; however, it may also lead to multiple or inconsistent standards.

Q# is a domain-specific programming language used for expressing quantum algorithms. It was initially released to the public by Microsoft as part of the Quantum Development Kit.