My Evil Plan for Greatly Improving Phobos's Docs

[Jack Stouffer via Digitalmars-d]

Submitting my thoughts here for critique. Please destroy.

Step One (this is the only part that I can't do myself):

https://issues.dlang.org/show_bug.cgi?id=15087

Currently, as function templates are auto attributed, there is no 
way to know if a template is nothrow, pure, @nogc, or @safe 
without trying to run it in your code and seeing if it will 
compile. That sucks and is tedious.

So what I propose is to add a new section in ddoc headers that 
allows maintainers of phobos to very visually show what 
attributes the template will have with what arguments.

Sure, sometimes the documentation will say that if the template 
is @nogc or not, but not all the time.

Also, this answers a common question new comers have, which is 
"doesn't the std lib use the GC?" To which the response is "Not 
all of it". To which the follow up is "Ok, what parts use it and 
what parts don't?", followed by crickets.

Step Two:

Once that section is added, write code to automatically find 
range and array based code in Phobos, run it with a static 
immutable array, and get the function attributes of the resulting 
template.

Step Three:

Take those resulting attributes and automatically update the docs 
for those functions.

Step Four:

Manually write the docs for everything else.