Add switch to compiler that causes Ddoc to issue error for public functions that:
1. have no Ddoc comment
2. have a non-void return but no Returns: section
3. have parameters but no Params: section
4. have no Example: section
Rationale:
Far too many functions in Phobos have essentially non-existent documentation.
Comment #1 by issues.dlang — 2015-03-18T19:02:36Z
In principle, I like the idea. However, I don't know about requiring Returns and Params sections and examples. There are plenty of cases where you want them, but there are also cases where they're so obvious that documenting them is redundant and therefore just creates noise in the file - especially on stuff like property functions.
Comment #2 by hsteoh — 2015-03-18T19:03:35Z
Note that Example: sections may have been generated by ddoc'd unittest blocks rather than an explicit Example section in the ddoc comment. In fact, ddoc's unittest blocks are preferred, because then you know that the test suite actually verifies that the example works, rather than some random code inside a ddoc'd comment that may or may not even compile, and of dubious correctness.
Comment #3 by doob — 2015-03-19T08:43:18Z
If you implement this, it should apply for protected symbols as well.
Comment #4 by robert.schadek — 2024-12-13T18:41:20Z