On 28/12/14 03:55, Xinok via Digitalmars-d wrote:
I'd like to contribute to the documentation (more within my skill level
anyways), but I'd like to follow some solid guidelines if I'm to do so. If we
don't have something like it already, perhaps we could create a page on the wiki
with some tips and conventions for writing documentation for Phobos (and if we
do, give me a link!). Then of course, we can incorporate some good and bad
examples which you've provided for us already.
Yup, clear rules for how things should be documented are really necessary. Then
it's trivial to find rulebreakers and fix them.
A speculative thought, given the remarks by Manu and others on how templated
signatures create hassle for comprehension. Is there any sane way that we could
auto-generate a "quasi-signature" for functions with the template types
specified? The idea would be that e.g. we could have the general signature, and
then provide a trivial example of how that signature resolves to something saner
if you know that (say) the input range is a built-in string, or built-in array,
or whatever.
So, say, you could have the general signature
S doSomethingWithAString(S s, ...) if (isSomeString!S)
and a note underneath providing the example with S == string:
string doSomethingWithAString(string s, ...)
Not sure if that's not too much work compared to just proper documentation, but
thought I'd float it.
BTW is it just me, or are the various isSomething methods of std.traits not
having documentation generated properly? See:
http://dlang.org/phobos/std_traits.html
... and try searching for, say, isBoolean, or isSomeString.
