Only main function is shown in docs

Help
1

Hi ! I followed the step describe inside the docs topic ‘Tips and tricks of the build system’ and added a documentation step to my code base. But only the main function is displayed ! Do I have to do something else to generate the full documentation ? I put some doc comments in a lot of places, so a lot more should be availlable.

2

I have understood why: when zig looked at my main.zig, only main was declared pub so the documentation only shows main. I will create a doc.zig file with

pub const sponge = @import("bob");

lines to generate the docs appropriately.

Edit: Types are displayed under the ‘Values’ category which is weird. When clicked only the source code is shown. Why are the library types shown properly under ‘Types’ then ?

Even weirder: when using:

pub const Sponge = @import("../Bob");

Sponge is incorrectly considered a value by the doc generator, but if I move doc.zig next to the source files, then it is considered a type.

3

I tried the documentation mechanism initially and figured out some rules.

  1. The documentation generation mechanism for executables and libraries seems to be quite different. For libraries, the documentation front page is based on the root_source_path, while for executables, the documentation front page has nothing to do with the root_source_file, and the project name is used as the default file for the documentation front page. For example, if the name of the exe or object you generate the documentation for is foo, then the default name used to generate the documentation is foo.zig. Without foo.zig, its first page is just based on the ascii order. I suspect that after you create a doc.zig, the reason why the first page uses its namespace is simply because the ascii order of doc.zig is before main.zig.
    I guess this may be intentional, because the standards for generating documentation for executable files are different, most people don’t care about the implementation of main in the root_source_file, and the root_source_file does not bear the responsibility of disclosing the public namespace required for documentation for executable files, so the project name file is chosen to disclose the public namespace required for documentation.
  2. Only other files in the same directory as the current document will be parsed by default, otherwise they will not be parsed, and they will be considered as values when unparsed. In addition, the parsing requirements of libraries and executable files also seem to be different. Generated documentation for executables almost always does not parse other files not in the same directory, whereas libraries seem to.
    I’m not sure if my conclusions are correct, this is my first attempt at automatically generating documentation.