json and ddoc

[Adam D. Ruppe]

On Wednesday, 1 August 2012 at 14:36:26 UTC, Philippe Sigaud 
wrote:
> Well, the comments are discarded as soon as lexical analysis is 
> done, I guess.

They are actually there if you do both -X and -D together.
(-X alone doesn't show it; it must be discarded then, but
-D keeps it).


The problem is though that it is the text from the comment
without any organization or macro expansion.

For example:

{
"name" : "map(fun...) if (fun.length >= 1)",
"kind" : "template",
"protection" : "public",
"comment" : "\nImplements the homonym function (also known as $(D 
transform)) present\nin many languages of    functional flavor. 
The call $(D map!(fun)(range))\nreturns a range of which elements 
are obtained by applying  $(D fun(x))\nleft to right for all $(D 
x) in $(D range). The original ranges are\nnot changed. 
Evaluation is   done lazily. The range returned by $(D 
map)\ncaches the last value such that evaluating $(D front) 
multiple    times\ndoes not result in multiple calls to $(D 
fun).\n\nExample:\n----\nint[] arr1 = [ 1, 2, 3, 4 ];\nint[]   
arr2 = [ 5, 6 ];\nauto squares = map!(\"a * a\")(chain(arr1, 
arr2));\nassert(equal(squares, [ 1, 4, 9, 16, 25, 36 
]));\n----\n\nMultiple functions can be passed to $(D map). In 
that case, the\nelement type of $(D map) is  a tuple containing 
one element for each\nfunction.\n\nExample:\n\n----\nauto arr1 = 
[ 1, 2, 3, 4 ];\nforeach   (e; map!(\"a + a\", \"a * 
a\")(arr1))\n{\n    writeln(e[0], \" \", e[1]);\n}\n----\n\nYou 
may alias $(D map)   with some function(s) to a symbol and 
use\nit separately:\n\n----\nalias map!(to!string) stringize;     
        \nassert(equal(stringize([ 1, 2, 3, 4 ]), [ \"1\", \"2\", 
\"3\", \"4\" ]));\n----\n",
"line" : 367,




I'd like to get the sections broken out and as many macros 
expanded
as possible, so the summary text in search results can look 
pretty.


One option is doing my own parsing, but Walter said the recursive
expansion in the macros was actually very tricky to get right.. so
I'd prefer to skip doing that again myself if I can.


> This generator does not give much information btw, but
> my impression is that people do not use it that much and,
> consequently, no feature request is emitted.

Yeah. It isn't bad though; more detailed than dpldocs.info
version 1.0 which did nothing more than grep '<a name' in
the generated html!