Skip to content

Latest commit

 

History

History
95 lines (65 loc) · 2.85 KB

README.md

File metadata and controls

95 lines (65 loc) · 2.85 KB
Raw

nixdoc

This tool is used to generate reference documentation for Nix library functions defined in Nixpkgs' lib.

Check out this example of documentation generated for the lib/strings.nix file.

It uses rnix to parse Nix source files, which are then transformed into a CommonMark (with some syntax extensions) representation of the function set.

Comment format

This tool implements a subset of the doc-comment standard specified in RFC-145/doc-comments. But, it is currently limited to generating documentation for statically analyzable attribute paths only. In the future, it could be the role of a Nix interpreter to obtain the values to be documented and their doc-comments.

It is important to start doc-comments with the additional asterisk (*) -> /** which renders as a doc-comment.

The content of the doc-comment should be some markdown. ( See Commonmark specification)

Example

The following is an example of markdown documentation for new and current users of nixdoc.

Sidenote: Indentation is automatically detected and should be consistent across the content.

If you are used to multiline-strings ('') in nix this should be intuitive to follow.

{
  /** 
    This function adds two numbers

    # Example

    ```nix
    add 4 5
    =>
    9
    ```

    # Type

    ```
    add :: Number -> Number -> Number
    ```

    # Arguments

    - a: The first number
    - b: The second number
    
  */
  add = a: b: a + b;
}

Outdated Format (Legacy)

Comment format

Identifiers are included in the documentation if they have a preceding comment in multiline syntax /* something */. You should consider migrating to the new format described above.

Two special line beginnings are recognised:

  • Example: Everything following this line will be assumed to be a verbatim usage example.
  • Type: This line will be interpreted as a faux type signature.

These will result in appropriate elements being inserted into the output.

Function arguments

Function arguments can be documented by prefixing them with a comment:

Note: This only works in the legacy format and should not be relied on anymore.

See the markdown example above how to write proper documentation.

For multiple reasons we cannot continue this feature.

/* This function does the thing a number of times. */
myFunction =
    # The thing to do
    thing:
    # How many times to do it
    n: doNTimes n thing

Caveats & TODOs

Please check the issues page.