On Thu, Jan 08, 2015 at 12:32:10AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: > I just experimented with a battery of macros (json.ddoc) for generating json > via ddoc. Results for std.algorithm are in > http://paste.ofcode.org/DFnxChvmRGJiXYpYYk2XWr. > > There are a couple of things that make the generated json invalid: > > 1. I couldn't get escaping to work. My ESCAPES is: > > ESCAPES=/\/\\/ /"/\"/ /&/&/ /</</ />/>/ > > So single backslashes will be doubled and quotes will be backslashed. > Nice. The trouble is, escaping only does its job sometimes but not > always. I haven't yet figured the circumstances.
About time somebody acknowledged that Ddoc's escaping mechanism leaves much to be desired! > 2. This was mentioned before - paragraph, whitespace and especially > newline handling are handled rather poorly in ddoc. The generated json > is full of newlines in the middle of strings, which are invalid in > json (\n must be used). I think every paragraph should be enclosed in > a $(DDOC_PARAGRAPH) macros that has single newlines replaced with > spaces. Alternatively, a built-in macro could escape strings > appropriately. Yep, also known for a long time and only now ackowledged: https://issues.dlang.org/show_bug.cgi?id=9731 > 3. Some descriptions feature multiple examples, leading to duplicate > "DDOC_EXAMPLES" keys. Json strongly discourages (at least) duplicate > keys in objects. There is no way to have some autoincrement thing that > generates "DDOC_EXAMPLES_1", "DDOC_EXAMPLES_2" etc. It could be argued > that that's an issue with the source, not the generator. [...] I disagree there's any issue with the source. The current system allows the very nice idiom of: /// ... some docs here auto myFunc(...) { ... } /// This example shows feature X of myFunc. unittest { ... } /// This example shows feature Y of myFunc. unittest { ... } The generated docs read like this: auto myFunc(...); ... some docs here This example shows feature X of myFunc. ... [first example here] This example shows feature Y of myFunc. ... [second example here] This is much more meaningful than a single gigantic example block that the reader has to parse in his head in order to get through everything being showcased. Of course, the mechanics of it can be improved -- ddoc should know better than to use the same heading "Examples:" over and over. Perhaps, in terms of the underlying macros, it should have some kind of autoincrementing label for each ddoc'd unittest block. T -- Stop staring at me like that! It's offens... no, you'll hurt your eyes!