Docs generation always includes imported packages

[EpicEric]

If I have a Pony program with a use statement, all code from other packages will be included in code documentation generation. Running ponyc mypkg --docs --pass docs on the following code:

use "collections"

class MyClass
  ...

will generate docs for mypkg, builtin, and collections. This is also the case for packages in Stable environments, and other packages that these packages include.

I understand how this is necessary for the stdlib, since it generates the docs for all packages through use statements. However, regular users are only interested in generating documentation of their own libraries. There should be some way to specify for which packages documentation should be generated, or at least the --docs flag description should be changed to describe this behaviour.

[EpicEric]

Another issue I've just noticed is that generated lib docs will also include links to actors/traits/etc. in the related packages (eg. if a function takes U8 as a parameter, the generated docs will include a link to primitive U8). Therefore, if we're going with option 1, it should be taken into account that these links must be removed, or changed to point to the official Pony docs page if it's from the standard library.

[SeanTAllen]

@EpicEric going to disagree with you on the "should be changed to point to official Pony docs page". Official pages update with each release. Documentation generation happens at a point in time. For a library, that could be different than the standard library because..

• it was generated from a previous version.
• it was generated from a custom version.

All that aside, how do you propose the compiler should know what packages it should generate documentation for and which it shouldn't?

[EpicEric]

Sorry for the late reply.

I think that the entire issue with the official doc pages being updated with each release would warrant different versions of the documentation to be hosted for every ponyc release, as to avoid API issues with mismatched versions, as well as reasons unrelated to this specific issue. But as you pointed out, this would not be suitable for custom ponyc distributions.

In that case, I would be fine with the alternative of simply removing links while still keeping a reference to stdlib/builtin objects, i.e. call objects by a full import path such as builtin.Array – similar to Java external objects for generated documentation (example: Kafka docs).

This could be extended to exclude different packages from docgen. If I was generating documentation for mypkg – and nothing else – with the following source:

use "collections"
use "./mysubpkg"

class MyClass
  ...

then any references to an object x from builtin, collections, and ./mysubpkg could be changed in the gendoc to, say, builtin.x, stdlib.collections.x and mypkg.mysubpkg.x respectively, or a different convention if there are better suggestions.

As to how the compiler would know which source files to consider part of generated documentation, there are a few options we could pass to a new ponyc flag:

1. Pass a whitelist of dirs with Pony source files (./mysubpkg,../anotherpkg) (the source dir is implicitly included)
2. Pass a whitelist of the Pony source files (*.pony,./mysubpkg/*.pony,../anotherpkg/*.pony) (the source files are NOT implicitly included)
3. Pass a whitelist of package names (mysubpkg,../anotherpkg) (the source package is implicitly included)
4. Pass a blacklist of package names (builtin,collection,notthispkg)

I don't know much about the compiler itself, but if it correlates objects with its origin package during compilation, the third option might be simpler to implement and easier to use, possibly even with the use of pony-stable. Of course, someone who has actually touched the compiler might know if these assumptions are baseless or not.