zigler v0.3.0-pre Zigler.Doc View Source

Translates the docstrings from your Zig code into Elixir documentation.

For instructions on how to incorporate this into an Elixir project, consult Mix.Tasks.ZigDoc

Documentation forms

Currently, Zigler recognizes four types of code segments which should be documented.

• functions
• types
• values
• errors

Functions

functions have the following signature:

pub fn <identifier>(<arguments>) <type> {

and may have the property of being comptime which is due to either the function being itself a comptime function or it having a comptime argument.

NB only pub functions are documented in Zigler, following the Elixir philosophy that only public functions should be documented.

Types

types have the following signature:

pub const <identifier>=<value>;

Values

values can have one of the following signatures:

• pub const <identifier>=<value>;
• pub var <identifier>=<value>;

Note that the constant value form is indistinguishable from the type form without doing a full parse and evaluation of the Zig code. In order to avoid doing this, to disambiguate between the two, you must prepend constant value docststrings with a !value token.

Example

/// !value
///
/// a constant representing the value 47.
pub const fortyseven = 47;

Errors

errors appear inside special error struct and should be documented at the per-value level:

Example

/// docstring for this error struct (if desired)
pub const my_error = error {
  /// docstring for ErrorEnum1
  ErrorEnum1,

  /// docstring for ErrorEnum2
  ErrorEnum2
}

Scope

This module will generate documentation from all Zig code that resides in the same code directory as the base module (or overridden directory, if applicable). Zig code in subdirectories will not be subjected to document generation.