digitalmars.D - My Evil Plan for Greatly Improving Phobos's Docs
- Jack Stouffer (26/26) Sep 18 2015 Submitting my thoughts here for critique. Please destroy.
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.
Sep 18 2015