Documentation Layout

[foobar]

On Wednesday, 28 March 2012 at 16:40:19 UTC, Nathan M. Swan wrote:
> On Wednesday, 28 March 2012 at 14:47:53 UTC, Adam D. Ruppe 
> wrote:
>> On Wednesday, 28 March 2012 at 06:20:57 UTC, James Miller 
>> wrote:
>>> 1. The "Jump To" index.
>>
>> I did a little program called improveddoc that builds nicer
>> tables:
>>
>> http://arsdnet.net/d-web-site/improveddoc.d
>>
>> makes:
>>
>> http://arsdnet.net/d-web-site/std_stdio.html
>>
>>
>> It does post-processing on the dom to build it.
>>
>
> That's pretty cool! I especially like the categories idea; it 
> reminds me of Apple's documentation for Cocoa. It really helps 
> you when you are thinking "I need a function which does...".
>
> NMS

Categories - worst idea ever.

What's better:
int a; // this is size
OR
int size;

Same thing applies here - code MUST be self documenting as much 
as possible.
D has an advanced module system yet people insist on treating D 
as if all we have are #includes. When that's coming from the 
developers of the standard library that looks like a huge warning 
sign to me.

While I applaud Adam's efforts I don't think that what we need is 
a complex multistage documentation system.

The recent posts about Rust peaked my curiosity and I picked at 
their docs. I was thoroughly impressed by the improvement they 
made since the last time I looked. The previous time (long ago) I 
quickly dismissed it but as their developer said himself it 
really shows that they eat their own dog food and the polish is 
very apparent.

The only think that annoyed me was the ridiculous abbreviation 
mess - looks like something a teenager on twitter would use. 
There's really no good reason to shorten return to "ret" and 
mutable to "mut". in fact, their code shows they started with 
"mutable" and then did a search/replace to shorten it. ?!?