[FEA] Add Doxygen CI check

[jrhemstad]

Is your feature request related to a problem? Please describe.

As #9355 shows, Doxygen documentation can easily get out of date.

No one likes out of date documentation. This leads to a bad experience for users and developers alike.

Describe the solution you'd like

Doxygen will generate warnings if the documentation does not match the code.

We should eliminate all current sources of warnings and then enable these warnings as a CI check to ensure Doxygen documentation stays up to date.

Additional context

This check should probably be optional at the beginning, but eventually should be required.

[davidwendt]

#9355 (comment)

[beckernick]

Discussed offline with @jrhemstad . Automation to keep Doxygen documentation up-to-date is worthwhile but not likely to get done in 21.12.

[github-actions]

This issue has been labeled inactive-30d due to no recent activity in the past 30 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed. This issue will be labeled inactive-90d if there is no activity in the next 60 days.

[karthikeyann]

Number of warnings in Doxygen are high.
To get opinion,
some of trivial functions without documentation are operator<, operator=, has_nulls, begin, end, etc.
Should they be skipped or warning ignored or documented? (documentation for method, parameters and return type)

[harrism]

Seems to me that public APIs should be documented. For detail APIs, we definitely have the option to skip. Is there any way to auto-generate docs for standard functions like operator<, operator=?

[github-actions]

This issue has been labeled inactive-30d due to no recent activity in the past 30 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed. This issue will be labeled inactive-90d if there is no activity in the next 60 days.

[github-actions]

This issue has been labeled inactive-90d due to no recent activity in the past 90 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed.

[karthikeyann]

Is there any way to auto-generate docs for standard functions like operator<, operator=?

CUB uses ALIASES. we could add aliases for these operators for ease the effort.

Another idea is to add custom filter command INPUT_FILTER.
I tested a simple example, for operator= as follows.

• created filter.sh with content sed 's/^.* operator=(/\/** @brief assignment operator. @returns reference to object **\/ \0/g' $@
• set INPUT_FILTER = /path/to/filter.sh in Doxyfile.
  All warnings related to operator= are gone.

how about we implement an input filter?
Note: As stated in https://www.doxygen.nl/manual/config.html#cfg_input_filter, we cannot insert or remove new lines.

Note that the filter must not add or remove lines; it is applied before the code is scanned, but not when the output code is generated. If lines are added or removed, the anchors will not be placed correctly.

[harrism]

Can the input filter only be applied to undocumented functions? Wouldn't want to overwrite existing ones.

Is there much value in doing it this way rather than fixing it once, manually? (Or running an automated fix just once) This would only fix the operators that we write the script to fix, and is only needed on public APIs. Does that account for a large fraction of the errors / warnings?

[karthikeyann]

input filter processes the entire file. so, filter should identify undocumented functions.
Running an automated or manual fix once is preferred.

The warnings are distributed among 67 files. 1483 warnings.
Here are the files with most warnings.

• 293 warnings from cudf/io/
• column, scalar, table
• strings, lists
• utilities, cudf_test