Incorporates Zig documentation from selected files into Elixir projects.

Usage

1. Include the zig files you wish to document in your project docs:

    def project do
      [
        docs: [
          ...
          zig_doc: [name_of_module: [file: "path/to/file.zig"]]
        ]
      ]
    end

2. (optional) alias Zig.Doc in your mix.exs:

   def project do
    [
      ...
      aliases: [
        docs: ["zig_doc"]
      ]
      ...
    ]
   end

   Note

   This step is required if you want HexDocs.pm to include the zig documentation with your main documentation.

Documentation forms

Currently, Zigler recognizes the following forms of documentation:

• files

  This form is set using the //! at the top of a document, and will be used as the "module-level" documentation for the ExDoc result.

• functions

  Public functions: pub const <identifier> = <value that is a function>; and publicly declared functions: pub fn <identifier>(<arguments>) <type> { <block> } are both recognized and converted to ExDoc-style function documentation.

• types

  pub const <type> = <expression that is a type>; is recognized and converted into ExDoc-style type documentation.

  functions which return type are also recognized and converted into type documentation.

• constants

  pub const <identifier> = <expression that is a constant>; is recognized and converted into ExDoc-style function documentation under the category Constants.

• variables

  pub var <identifier> = ...; is recognized and converted into ExDoc-style function documentation under the category Variables.

Tags

preamble documentation comments like so

\\\ <!-- <tag0>; <tag1>;...;<tagn> -->

to tag the content. Currently available tags:

• ignore: ignores the content.
• topic: <topic>: (non-type functions only) sets the topic of the content. This will be used to group functions in the ExDoc output, the function group will be rendered as Functions (<topic>).
• args: <arg0>,<arg1>,...,<argn> (const functions only) sets argument names when the function is rendered as a constant. Use _ to signify that the name should not be used.

Warning

Currently Zig.Doc is lazily written to support the use case for beam.zig found in the the main Zigler project. It is very likely that custom zig files used in a nif might not be correctly parsed. If you find this to be the case, please file an issue at: https://github.com/E-xyza/zig_doc/issues