Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 28 December 2015 at 23:05:28 UTC, Andrei Alexandrescu 
wrote:
> (a) is the new proposed system differentiated enough to justify 
> its existence and motivate others to join in?


I was just watching my newbie friend try to manipulate 
directories in D. His first instinct was to go to std.path. I 
decided to edit std.path to add a note in the header "if you want 
to get path names from a directory, use std.file".

Linking to std.file proved to be a huge hassle. Sure, I could 
just $(LINK2 std_file.html, std.file) like Phobos does in other 
places, but alas, that breaks ddox.

http://dlang.org/library/std/algorithm.html

Click the "See also Reference on ranges" there and observe the 
404.

So I wanted to define a new macro called MREF so you'd write it 
$(MREF std,file) and it would replace with underscores on ddoc, 
slashes on ddox (and dots on my docs).

Easy, right? Wait, XREF doesn't work right on modules, it expects 
the second arg to be a function and links break in some places if 
you leave it blank, and it doesn't work on submodules... can't 
there just be a REF thing?

I guess not, the system is too complicated. Whatever though, I'll 
make my new MREF, or module reference. (Am I seriously the first 
one to do this?)

	Check out $(MREF std,file) and $(MREF std,algorithm,searching)!

	Macros:
		MREF_HELPER=_$1$(MREF_HELPER $+)
		MREF=$1$(MREF_HELPER $+).html

Wow, it works! (Well, basically. It doesn't work if the module 
has only one name, like object.d, but we can special case that 
one.)


But now, where do I put it? I grep for XREF in dlang.org/*.ddoc 
and find a few candidates then check the wiki 
http://wiki.dlang.org/Contributing_to_dlang.org#Macro_Definition_Batteries:_.ddoc_files to see what it says.

...it returned files that aren't listed there... what should I do 
with them? Oh dear this is taking too much brain power, I just 
wanted to add a sentence linking people to the other module!




BTW this is why my thing separates all the filenames with dots, 
just like D itself does. Predictable, even without semantic 
analysis!


This huge friction has killed my desire to contribute to Phobos 
before and it looks like it is again.

the difference is this time, I have my own fork so the community 
doesn't have to lose out.