Documentation Improvement Initiative

[RazvanN]

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>

The elephant in the room is the DMD codebase. Examples:

1. https://dlang.org/phobos/dmd_apply.html

Empty page, with no explanation of what is the purpose of the page

2. https://dlang.org/phobos/dmd_attrib.html

Most of the documentation is non-existent, lacking or 
insufficient to understand what happend

3. https://dlang.org/phobos/dmd_expression.html

Most classes have no explanation. I would expect that each class 
would be followed by some pieces of code that highlight to what 
code the class maps

4. https://dlang.org/phobos/dmd_traits.html

It's missing documentation for the single most important function 
in the file: semanticTraits which does semantic analysis for 
`__traits()`

These are just a few examples, but the dmd codebase is full of 
such examples. In addition, now that dmd as a library is 
available, things are worse because people have no way of using 
it effectively since they cannot understand what's happening 
there. Moreover, it is impossible to attract new contributors 
when a complex piece of software is severely underdocumented.

Besides documenting this code, I think it is necessary in some 
situations to refactor the code so that we can highlight the 
documentation. For example, the traits file in dmd (link number 
4) contains a single function `semanticTraits` which has 1500 
lines of code and contains the whole traits semantic logic 
organized as if/else branches. The documentation for those 
branches will not be publicly available, so we must refactor the 
code to use separate functions. This will make the code cleaner 
and help us with documentation which is a great plus.
I gave this example because it is typical for a lot of situations 
in the dmd codebase. So not only it is a great chance to improve 
the documentation of dmd, but also to make the codebase more 
modern.