Season of Docs

[Dennis]

On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:
> Where do you think D has the deepest need of good technical 
> documentation?

When it comes to technical documentation, the dmd codebase could 
really use some comments. Take these files for example:
https://dlang.org/phobos/dmd_s2ir.html
https://dlang.org/phobos/dmd_todt.html
https://dlang.org/phobos/dmd_eh.html
Eh? Those acronyms aren't immediately obvious, and there isn't a 
header that explains what the module is about.

Not to mention the back-end, where you have such descriptive 
filenames as 'cod1.d' to 'cod5.d', and documentation completely 
missing:
https://dlang.org/phobos/dmd_backend_cod1.html
"Oh No! Page Not Found"

This is more helpful already:
https://wiki.dlang.org/DMD_Source_Guide

But it is full of statements like:
"Note: This section may be considerably outdated. Please bring it 
up to date where you can."

An this gem:
"Symbol - Appears to have something to do with the names used by 
the linker."
This is what I expect to hear from a reverse engineering project, 
not an open source codebase.

---

Secondly, the command line reference of dmd is pretty bare too

https://dlang.org/dmd-windows.html

-shared
     Generate DLL library

If I interpreted https://wiki.dlang.org/Win32_DLLs_in_D 
correctly, it doesn't actually generate a DLL, it just disables 
an optimization that's not valid in DLL's. You still have to put 
the resulting .obj through a linker manually or add 
-of=mylibrary.dll.

---

Finally, Dub.

Possibly technical documentation isn't the solution here, but I 
still wanted to mention how often I go back to the json/sdl 
package reference trying to get Something Simple done. Build 
options, -settings, -requirements, -types and -configurations are 
mentioned. It still confuses me.
More of https://github.com/dlang/dub/wiki/Cookbook would be nice.

https://dub.pm/advanced_usage.html
"Execute dub <command> -h for more information on these commands."

Please just include all info in the docs thank you very much.