new documentation format for std.algorithm

[Andrei Alexandrescu]

On 2/2/11 10:06 AM, Adam Ruppe wrote:
> Andrei Alexandrescu:
>> Hmmm, this wrong jumping is a problem. I'll look into it. Offhand I
>> don't know how to distinguish in the generated doc between an enum value
>> and a function, but Adam did it. Adam?
>
> My method is to track the level of nesting. The more<dl>  tags above
> you in the tag tree, the further down you are.
>
> The generated html puts everything in a<dl>  html tag. It goes:
>
> <dl>
>     <dt>Function<u>name</u>  and prototype</dt>
>     <dd>Information about it</dd>
> </dl>
>
> For enums (and probably structs/class methods too, but I haven't
> confirmed yet), the sub-members are in that dd, like so:
>
> <dl>
>      <dt>Enum Name</dt>
>      <dd>Enum description
>         <dl>
>             <dt>Member #1 name</dt>
>             <dd>Member #1 description</dd>
>         </dl>
>       </dd>
> </dl>
>
>
>
> So, if you keep track of how many<dl>'s are above you in the
> tree, you know what your parent is - are you a top level function
> or a member of another object?
>
> If you're a member of another object, you go up the tree a couple
> levels (get past your<dl>, then past the enclosing<dd>) and
> find the<dt>  that is the last sibling to your grandparent.
>
> That holds the name of the enum.
>
> Here's my javascript implementation:
>
> function getParentTerm(e) {
> 	while(e) {
> 		if(e.tagName == "DD")
> 			return e;
> 		e = e.parentNode;
> 	}
>
> 	// we have the definition, gotta get the term right above it
>
> 	if(e == null)
> 		return null; // has no parent
>
> 	var r;
> 	var arr = e.parentNode.childNodes;
> 	for(var p = 0; p<  arr.length; p++) {
> 		var a = arr[p];
> 		if(a.tagName == "DT")
> 			r = a; // store the last term we saw...
> 		if(a == e) // if we're back to ourselves...
> 			return r; // ... the last term is the answer
> 	}
> 	//assert(0);
> }
>
>
>
> Since the actual function names are underlined, you can get
> a full name by searching the returned term for a<u>  tag and
> pulling it out. While parent !is null, name = parent.name ~ "." ~
> name, done.
>
> If you found the child a[name] elements and replaced the name
> attribute with the result from above, the links would all work too.
>
>
> I have an almost working D implementation too, but the HTML isn't
> well formed xml so my library butchers it a bit on output. That needs
> to be fixed before ditching the javascript. Then, I figure, we can
> add the helper program in between dmd itself and the live site.
>
>
> Anyway, I know what's wrong and how to fix it, but haven't written
> the last pieces of code to actually do it yet... after that, we
> just have some presentation issues to finalize and we're set.

Got it, thanks. Perhaps indeed a ddoc change would make this easier.

Andrei