Documentation Improvement Initiative

[Adam D. Ruppe]

On Wednesday, 19 February 2020 at 17:09:02 UTC, bachmeier wrote:
> The other thing that immediately stands out to me when I click 
> a random project's documentation, like this:
> https://hunt-database.dpldocs.info/hunt.html
> is that the page doesn't contain a lot of information.

That's because the author of that project wrote near-zero 
documentation. I can't fix that myself.

> I think it would be better to be able to click to expand if you 
> want information about types. iota, for instance, is cluttered 
> but the extra information doesn't bring much to the table.

Yeah, the members list is one of the things I'm not really happy 
with.

I'm not sure there's any real value in separating out classes, 
structs, enums, etc., and I do think it shows too much there.

I did just fix a bug in it so it doesn't duplicate those function 
prototypes (actually the technical difference was they had 
separate constraints, but sine that isn't visible here it looked 
like a total duplicate and waste) anymore.

But the other worry is the information on the right. Part of this 
is that the documentation in the source doesn't really follow the 
spec. https://dlang.org/spec/ddoc.html#summary says the first 
thing in a ddoc comment is supposed to be a short summary. Then 
you put in a paragraph break and write the rest of your details.

Though maybe I can just limit the size on my side though.

But yeah this members list is one of the things I was never 
actually happy with so I'm open to any ideas to change it, 
potentially up to a total replacement.

if you refresh this now you can see some changes:
http://dpldocs.info/experimental-docs/std.range.html


> I also don't understand why the functions are listed twice.

Ddoc's limitations led to the authors writing it out by hand, but 
then my  generator auto-generates a list and doesn't realize the 
hand-written list is there (and even if it did, the hand written 
list is frequently incomplete!).

So now it has both.

The ddox version on the official site does basically the same 
thing for the same reason:

  https://dlang.org/library/std/range.html

ddox strips types out of its listing on the left, something I've 
also considered, but I find types to be really useful...


My generator also has the ability to group functions into 
categories

http://dpldocs.info/experimental-docs/arsd.nanovega.html#members

but that requires a tag be added to the source and Phobos does 
the hand-written tables instead of tags on the functions since 
ddoc doesn't support tagging anyway. so bleh.