www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Simple step to making Ddoc better

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
There's no better way to find awkwardnesses in a design than trying to 
explain it to someone.

Could someone destroy https://issues.dlang.org/show_bug.cgi?id=15460? 
Should take minutes.


Thanks,

Andrei
Dec 18 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:09:43 UTC, Andrei Alexandrescu 
wrote:
 Could someone destroy 
 https://issues.dlang.org/show_bug.cgi?id=15460? Should take 
 minutes.
I kinda want to toy with cross referencing too. I have an idea: a magic macro that expands like Object in specified DDoc contexts to $(D_SYMBOL_NAME object Object) yes, it outputs the full name, but not as dots - as different macro arguments. Then we can make a recursive macro to put it back together as like phobos/object_Object or something. idk yet, but I think we can do something. And we need crosslinking somehow. Even just putting the dotted name that we can process in another list (my dpldocs.info for example can find a page) is better than nothing. I have so much stuff to do but blargh, I'll look at all this.
Dec 18 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/18/2015 11:20 AM, Adam D. Ruppe wrote:
 On Friday, 18 December 2015 at 16:09:43 UTC, Andrei Alexandrescu wrote:
 Could someone destroy https://issues.dlang.org/show_bug.cgi?id=15460?
 Should take minutes.
I kinda want to toy with cross referencing too. I have an idea: a magic macro that expands like Object in specified DDoc contexts to $(D_SYMBOL_NAME object Object) yes, it outputs the full name, but not as dots - as different macro arguments. Then we can make a recursive macro to put it back together as like phobos/object_Object or something. idk yet, but I think we can do something. And we need crosslinking somehow. Even just putting the dotted name that we can process in another list (my dpldocs.info for example can find a page) is better than nothing. I have so much stuff to do but blargh, I'll look at all this.
What's needed here is to wrap all raw text in DDOC_RAWTEXT as I proposed a few days ago. Then external tooling makes cross referencing trivial. Wanna work on that? -- Andrei
Dec 18 2015
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:28:31 UTC, Andrei Alexandrescu 
wrote:
 What's needed here is to wrap all raw text in DDOC_RAWTEXT as I 
 proposed a few days ago. Then external tooling makes cross 
 referencing trivial. Wanna work on that? -- Andrei
I don't agree that would help - what I want is when a code example is like: --- import std.stdio; void foo(File f); --- I want DDoc to look up what File means (that it is from std.stdio and not from some other module, for example) and tell me that in the generated code somehow. So this is already being syntax highlighted, I want it to look up more. A big potential problem there is that not all examples are complete programs that will compile, so it won't always work. But we can cross that bridge when we come to it.
Dec 18 2015
prev sibling next sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 18.12.2015 um 17:28 schrieb Andrei Alexandrescu:
 On 12/18/2015 11:20 AM, Adam D. Ruppe wrote:
 On Friday, 18 December 2015 at 16:09:43 UTC, Andrei Alexandrescu wrote:
 Could someone destroy https://issues.dlang.org/show_bug.cgi?id=15460?
 Should take minutes.
I kinda want to toy with cross referencing too. I have an idea: a magic macro that expands like Object in specified DDoc contexts to $(D_SYMBOL_NAME object Object) yes, it outputs the full name, but not as dots - as different macro arguments. Then we can make a recursive macro to put it back together as like phobos/object_Object or something. idk yet, but I think we can do something. And we need crosslinking somehow. Even just putting the dotted name that we can process in another list (my dpldocs.info for example can find a page) is better than nothing. I have so much stuff to do but blargh, I'll look at all this.
What's needed here is to wrap all raw text in DDOC_RAWTEXT as I proposed a few days ago. Then external tooling makes cross referencing trivial. Wanna work on that? -- Andrei
Just a quick reminder: https://dlang.org/library/ already has automatic cross-referencing*. If we agree to pursue this as a replacement to the current documentation, I suggest to focus efforts on that. I can work on the generator itself, but I lack the time to go through all of Phobos to fix custom-macro related glitches, such as [1], so some help is required. * Currently it looks at all words in a text to find symbols, but once the documentation is adjusted accordingly, it would be switched to just look within `code` or $(D code) parts. [1]: https://issues.dlang.org/show_bug.cgi?id=14403
Dec 18 2015
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:42:14 UTC, Sönke Ludwig wrote:
 * Currently it looks at all words in a text to find symbols, 
 but once the documentation is adjusted accordingly, it would be 
 switched to just look within `code` or $(D code) parts.
What about examples and prototypes? That reminds me, formatting the prototypes I think is high value too. DDox does ok: https://dlang.org/library/std/algorithm/comparison/levenshtein_distance.html But I still think we can do a lot better.
Dec 18 2015
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 18.12.2015 um 17:48 schrieb Adam D. Ruppe:
 On Friday, 18 December 2015 at 16:42:14 UTC, Sönke Ludwig wrote:
 * Currently it looks at all words in a text to find symbols, but once
 the documentation is adjusted accordingly, it would be switched to
 just look within `code` or $(D code) parts.
What about examples and prototypes?
It does that, too, forgot to mention that.
 That reminds me, formatting the prototypes I think is high value too.
 DDox does ok:

 https://dlang.org/library/std/algorithm/comparison/levenshtein_distance.html


 But I still think we can do a lot better.
Agreed, do you have concrete ideas? One thing that could also be interesting (and easy to do) would be to add parameter names in the "Functions" overview tables, so that levenshteinDistance gets listed as levenshteinDistance(equals, s, t). That could replace the manually authored cheat sheet in many cases.
Dec 18 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:57:44 UTC, Sönke Ludwig wrote:
 Agreed, do you have concrete ideas?
I think white space in the declaration would make a huge difference, and your page does that already somewhat, putting the params on separate lines. Here's the ddoc definition for levenshteinDistance: http://dlang.org/phobos/std_algorithm_comparison.html#.levenshteinDistance --- size_t levenshteinDistance(alias equals = (a, b) => a == b, Range1, Range2)(Range1 s, Range2 t) if (isForwardRange!Range1 && isForwardRange!Range2); --- Here's the ddox definition: https://dlang.org/library/std/algorithm/comparison/levenshtein_distance.html --- size_t levenshteinDistance(alias equals, Range1, Range2)( Range1 s, Range2 t ) if (isForwardRange!Range1 && isForwardRange!Range2); --- I think the second one is nicer looking, but it also didn't show the default argument and the template args could be broken more. I think I'd write it: --- size_t levenshteinDistance ( alias equals = (a, b) => a == b, Range1, Range2 ) ( Range1 s, Range2 t ) if ( isForwardRange!Range1 && isForwardRange!Range2 ); --- Or something like that. Plus syntax highlighting and linking of recognized things. The parameters should link to details in the Params: section, if present. `isForwardRange` should link back to that definition. Heck, I wouldn't mind if `size_t` was a link too. You know, I wouldn't even hate it if hovering over `Range1` in the constraint or either param list highlighted it in the other places it is mentioned too. A bit of script required but it can help to visually tie it all in. We can't rearrange the constraint to put them right next to each other like `Range1, // isForwardRange!Range1` in the CT param list since template constraints can be arbitrarily complex, but some dynamic highlighting can achieve a similar effect. One item per line might seem like overkill here, but I think it pays off on complex types, specializations, or default values. `(alias equals = (a, b) => a == b, Range1, Range2)` is kinda a handful already and not even all that complex. Though, if the names and types were highlighted it might mitigate this more than plain text can allow. I just really strongly feel that white space is our friend here and we ought to be using it. Color and dynamic highlighting is gravy on top of it.
 One thing that could also be interesting (and easy to do) would 
 be to add parameter names in the "Functions" overview tables, 
 so that levenshteinDistance gets listed as 
 levenshteinDistance(equals, s, t). That could replace the 
 manually authored cheat sheet in many cases.
Yes, indeed.
Dec 18 2015
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:28:31 UTC, Andrei Alexandrescu 
wrote:
 What's needed here is to wrap all raw text in DDOC_RAWTEXT as I
BTW I think this is easy and backward compatible, I might just do it anyway, but I don't think it will help here.
Dec 18 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/18/2015 11:44 AM, Adam D. Ruppe wrote:
 On Friday, 18 December 2015 at 16:28:31 UTC, Andrei Alexandrescu wrote:
 What's needed here is to wrap all raw text in DDOC_RAWTEXT as I
BTW I think this is easy and backward compatible, I might just do it anyway, but I don't think it will help here.
You are correct, I was being confused about your point. And yes DDOC_RAWTEXT is backward compatible and useful. Thanks!! -- Andrei
Dec 18 2015
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 18 December 2015 at 16:55:58 UTC, Andrei Alexandrescu 
wrote:
 You are correct, I was being confused about your point. And yes 
 DDOC_RAWTEXT is backward compatible and useful. Thanks!! -- 
 Andrei
Eh, it isn't as easy as I thought though because everything in ddoc is inside a macro at some level. It would have to be something like a proprocessor on the user input that skips balanced parens. Still doable, but not as simple.
Dec 18 2015