Documentation linter

[ahcorde]

Documentation linter

[gavanderhoorn]

This issue is to define how we want to check that all API is documented. In particular to check if there are undocumented functions, parameters or attributes in the code.

Are you planning to use some tooling for this?

I've used this (with varying success) in the past: psycofdj/coverxygen.

[jacobperron]

If the proposed ament_doxygen tool is going to do more than documentation related linter checks (e.g. actually generate HTML documentation), then it can probably live in it's own repository instead of ament_lint.

I wonder if we really need a rosdoc.yaml file. Couldn't the same information be given to the proposed ament_doxygen command? I'm not sure what this looks like in the context of a pure Python package (or if pure Python packages are in scope).

This setup I think it's more scalable if decide to change the Doxygen template then we don't need to commit in every repository and it will allow to point the installed folder.

It might also be valuable to let packages supply their own Doxygen files (e.g. override the default provided by ament_doxygen).

[ahcorde]

I have been reading the article "ROS 2 Documentation System" which is not public yet, bit it's available in the ros2/desing repository. This article describes the proposed system for doing documentation for ROS 2. It has some TODOs and it was original wrote by @wjwwood , I don't know what is the status/relevance of this article because last commit was done 3 Feb 2016. Can you provide a quick update about this article? or links to futher discussions?

Another maybe related topic is in the REP 149 (Package Manifest Format Three Specification) exists a field called <doc_depend> but the REP indicates that this is unused right now:

The current version of the buildsystem does not provide any documentation specific functionality

Is there any ideas about how this field should be used in the future? Because this field may help with the tags in Doxygen.

[dirk-thomas]

The current version of the buildsystem does not provide any documentation specific functionality

While the build system doesn't utilize doc dependencies atm the buildfarm does within the ROS 1 doc jobs.

[ahcorde]

I'm not sure what this looks like in the context of a pure Python package (or if pure Python packages are in scope).

I started doing this for the Quality Level 1 packages which are mainly C++, I think that Python uses Sphinx to generate the documentation. Maybe I can generalize this new linter and call it ament_lint_doc to include both engines.

It might also be valuable to let packages supply their own Doxygen files (e.g. override the default provided by ament_doxygen).

For packages such as rclcpp that generates some files, we should override or at least generate a new Doxyfile on in the build directory with the right path to the installed include folder