www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Inline code in the docs - the correct way

reply Jakub =?UTF-8?B?xYFhYmFq?= <uaaabbjjkl gmail.com> writes:
What is the current state of the art of writing inline code in 
the documentation?

Wiki says "use `...` instead of $(D ...)": 
https://wiki.dlang.org/Contributing_to_Phobos#Documentation_style.

Some arguments made here: 
https://github.com/dlang/phobos/pull/5183#issuecomment-281895450 
suggest that backticks, among others, may not work well with 
cross-references as they may contain a code of a different 
language than D.

Still, pretty recent PRs suggest that backticks should be used, 
but only for single words:
- https://github.com/dlang/phobos/pull/5801
- https://github.com/dlang/phobos/pull/5970

I thought of updating the wiki to match the apparent consensus in 
this regard but wanted to make sure if it's really the way to go.
Jan 31
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Jan 31, 2018 at 03:40:04PM +0000, Jakub Łabaj via Digitalmars-d wrote:
 What is the current state of the art of writing inline code in the
 documentation?
 
 Wiki says "use `...` instead of $(D ...)":
 https://wiki.dlang.org/Contributing_to_Phobos#Documentation_style.
 
 Some arguments made here:
 https://github.com/dlang/phobos/pull/5183#issuecomment-281895450
 suggest that backticks, among others, may not work well with
 cross-references as they may contain a code of a different language
 than D.
 
 Still, pretty recent PRs suggest that backticks should be used, but
 only for single words:
 - https://github.com/dlang/phobos/pull/5801
 - https://github.com/dlang/phobos/pull/5970
 
 I thought of updating the wiki to match the apparent consensus in this
 regard but wanted to make sure if it's really the way to go.
AFAIK, backticks is preferred because $(D ...) syntax is noisier, and harder to read in the source code. But otherwise, the two are equivalent. (In fact, backticks translate directly into $(D ...) in the ddoc code. They are just syntactic sugar.) But if your code snippet is longer than a line, you should use inline code block syntax: /** blah blah discussion here ---- /* code here */ void main() { ... } ---- blah blah discussion here */ T -- In a world without fences, who needs Windows and Gates? -- Christian Surchi
Jan 31
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 31 January 2018 at 17:14:56 UTC, H. S. Teoh wrote:
 But otherwise, the two are
 equivalent. (In fact, backticks translate directly into $(D 
 ...) in the ddoc code. They are just syntactic sugar.)
No, they aren't. The `` is different in several ways including doing character escaping that macros are incapable of, and it expands to BACKTICK, not D. Read the comment of mine linked by the OP. They are intended to be separate, but you are right that the lighter syntax is getting more attention, much to my chagrin.
Jan 31
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Jan 31, 2018 at 06:31:34PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Wednesday, 31 January 2018 at 17:14:56 UTC, H. S. Teoh wrote:
 But otherwise, the two are equivalent. (In fact, backticks translate
 directly into $(D ...) in the ddoc code. They are just syntactic
 sugar.)
No, they aren't. The `` is different in several ways including doing character escaping that macros are incapable of, and it expands to BACKTICK, not D. Read the comment of mine linked by the OP.
Ah, then I stand corrected.
 They are intended to be separate, but you are right that the lighter
 syntax is getting more attention, much to my chagrin.
Coming from you, I'm a little surprised. Weren't you one of the people complaining that ddoc macro syntax is ugly? I actually share that sentiment, and have been avoiding using any explicit macro markup in my ddoc comments until `` came along that didn't make the source code (IMO) unreadable. Even now, I still refuse to use anything more than that in my own code, at least not directly (I did do one or two ddoc template customizations, but would not insert that into my source code itself). Though of course, when contributing to Phobos I just have to follow whatever other Phobos code does. (Still, I try to avoid touching ddoc macro syntax where possible. It makes me feel like I have to wash my hands afterwards.) T -- One reason that few people are aware there are programs running the internet is that they never crash in any significant way: the free software underlying the internet is reliable to the point of invisibility. -- Glyn Moody, from the article "Giving it all away"
Jan 31
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 31 January 2018 at 21:34:47 UTC, H. S. Teoh wrote:
 Coming from you, I'm a little surprised.  Weren't you one of 
 the people complaining that ddoc macro syntax is ugly?
$(H1 Rebuttal) It depends how you use it. For large blocks or for small, special bits, it doesn't bother me. So if I wanted to $(I point out) something in the middle, it doesn't bug me. $(QUOTE Similarly, if I want to call out a whole block of text, ddoc has some nice bits, like how easily it nests and can be added around existing text without thinking about it. ) $(H1 But...) $(P Where it starts to bug me is when you are using it $(I all over the place), especially with $(B random nesting).) $(P It is obnoxious to write on every paragraph, for example.) $(TABLE $(TR $(TD $(P or trying to make a table out of it) $(P especially if it is randomly formatted in the source. $(BR) $(B yikes!))))) Phobos does a lot of that latter filth, and almost never even tries to format it, making it even worse. My adrdox tries to eliminate most of the latter stuff Phobos uses, but it retains the ddoc syntax for the stuff I don't mind. In fact, I kinda $(B prefer) it to the *markdown way* in some places, since at least the ddoc is deliberate. Only thing that bugs me is when I try to write :) or 1) or similar in there but I plan to fix that. Now though, inline code like $(D) and $(REF) are ambiguous. They are short enough that they'd normally fall into my "ok with it" zone like $(B)... but they are also so common and I want to encourage their use. And having three shifted characters that must appear in order is kinda painful to type - it just breaks up the thought process, and can get somewhat weird to look at. So like I probably wouldn't write "The $(REF SimpleWindow) class is used along with the $(REF EventLoop) to create a window." without actually thinking about it, but "The [SimpleWindow] class is used with [EventLoop]" is almost thoughtless to type. The latter may be slightly easier to read.... but I think the bigger difference is just the friction in typing it the first time in this case. Emphasis ought to be rare anyway, but interlinking ought to be very common. I'm very very skeptical of claims of "it is faster to type" being significant... but easier to type I do think makes it more likely to be used. Most macros I think ought not be used frequently but this is different. BTW adrdox does [reference] instead of `reference` linking because of what I said before: `code` is too generic. It isn't necessarily a link. Moreover, my [reference|also allows alternative text to display], which wouldn't work well in ``.
Jan 31
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Jan 31, 2018 at 10:55:38PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Wednesday, 31 January 2018 at 21:34:47 UTC, H. S. Teoh wrote:
 Coming from you, I'm a little surprised.  Weren't you one of the
 people complaining that ddoc macro syntax is ugly?
$(H1 Rebuttal) It depends how you use it. For large blocks or for small, special bits, it doesn't bother me. So if I wanted to $(I point out) something in the middle, it doesn't bug me.
Then I guess we differ on this point. While I think the ddoc macro system, *as a macro system*, is pretty elegant in and of itself, I personally can't stand mixing it in with ddoc comments, which I've grown accustomed to be plain ole text, like other code comments. Interpreted differently by the compiler, sure. But having a different syntax? I find it too jarring and distracting. [...]
 $(P Where it starts to bug me is when you are using it $(I all over the
 place), especially with $(B random nesting).)
 
 $(P It is obnoxious to write on every paragraph, for example.)
 
 $(TABLE $(TR $(TD $(P or trying to make a table out of it) $(P especially if
 it is
 randomly formatted in the source. $(BR) $(B yikes!)))))
Urgh, as if $(I this syntax) isn't already jarring enough, inserting what is basically a poor man's transliteration of HTML into ddoc syntax into source code is just ... it makes me wanna reach for the 'mark-block-delete' key combo in Vim. In general, almost all text macro / formatting systems, from LaTeX to HTML to ddoc, are universally ugly and verbose when it comes to tables, and makes my eyes bleed. The only exception I've found so far is markdown, where you can actually write this: |Blah|Blah| |----|----| |abc |def | |ghi |jkl | It's not perfect, but it's worlds better than the line noise syntax of the alternatives. [...]
 My adrdox tries to eliminate most of the latter stuff Phobos uses, but
 it retains the ddoc syntax for the stuff I don't mind. In fact, I
 kinda $(B prefer) it to the *markdown way* in some places, since at
 least the ddoc is deliberate. Only thing that bugs me is when I try to
 write :) or 1) or similar in there but I plan to fix that.
Yeah, I'm not really a fan of *...* or _..._ in markdown syntax. It's just too easy to mix them up / misidentify them for identifiers in code or expressions, esp. if C-like pointer dereference syntax is used. Though I suppose that's what `...` is for. But then again, I rarely find the need to have emphasis in technical docs, so it's not a biggie. And I do still prefer *...* over $(B ...). I just don't like alphabetical macro names interspersed with text; it makes it hard to parse the text with the eye.
 Now though, inline code like $(D) and $(REF) are ambiguous. They are
 short enough that they'd normally fall into my "ok with it" zone like
 $(B)... but they are also so common and I want to encourage their use.
 And having three shifted characters that must appear in order is kinda
 painful to type - it just breaks up the thought process, and can get
 somewhat weird to look at.
 
 So like I probably wouldn't write "The $(REF SimpleWindow) class is
 used along with the $(REF EventLoop) to create a window." without
 actually thinking about it, but "The [SimpleWindow] class is used with
 [EventLoop]" is almost thoughtless to type.
This is why I prefer markdown-style syntax.
 The latter may be slightly easier to read.... but I think the bigger
 difference is just the friction in typing it the first time in this
 case.  Emphasis ought to be rare anyway, but interlinking ought to be
 very common.  I'm very very skeptical of claims of "it is faster to
 type" being significant... but easier to type I do think makes it more
 likely to be used. Most macros I think ought not be used frequently
 but this is different.
Actually, for me it's not so much a matter of "it's faster to type"; it's more of an issue of "when I'm reading (and presumably thinking (hard) about) source code, do I really want to expend the mental resources to parse the syntax of yet another embedded DSL inside a *comment*?". If I had my way, I would just write a normal comment as opposed to a doc comment. What makes the doc proposition attractive is that, in an ideal world, a "normal" comment can be automatically translated into nice docs without needing to pepper-spray it with foreign syntax particles, so that I can read the comment while working on the code, in addition to having nice docs to show to others in a format they prefer, like HTML or whatever. That's why I would actually welcome markdown-like syntax in ddoc. Yeah, it has limitations and sux in many ways, but IMNSHO you shouldn't be reimplementing complex HTML syntax inside a doc comment anyway -- leave that to an external templating engine or whatever you wish to use, and just let the doc comment be as readable as possible *as source code*.
 BTW adrdox does [reference] instead of `reference` linking because of
 what I said before: `code` is too generic. It isn't necessarily a
 link. Moreover, my [reference|also allows alternative text to
 display], which wouldn't work well in ``.
I wouldn't expect `...` to produce a link; it should just be formatted differently (typically in monospace font) to indicate that it's a code snippet. Using [...] syntax for links makes more sense to me, even though personally, I really prefer to just write plain ole text and paste the URL in its own indented block: http://example.nowhere.edu/blah/blah/blah Let the templating engine or whatever identify the link for me and produce whatever HTML spew is necessary to make it work in a browser, just leave my source code alone already! T -- Shin: (n.) A device for finding furniture in the dark.
Jan 31
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
FYI I am changing the subject line with this post since it is 
branching off the original question of simple best practices of 
code in ddoc.


On Thursday, 1 February 2018 at 00:19:53 UTC, H. S. Teoh wrote:
 In general, almost all text macro / formatting systems, from 
 LaTeX to HTML to ddoc, are universally ugly and verbose when it 
 comes to tables, and makes my eyes bleed. The only exception 
 I've found so far is markdown, where you can actually write 
 this:

 	|Blah|Blah|
 	|----|----|
 	|abc |def |
 	|ghi |jkl |

 It's not perfect, but it's worlds better than the line noise 
 syntax of the alternatives.
So adrdox actually supports that (though you must label it), but I actually kinda hate it because it is enormously difficult to edit. Earlier today, in a work call, the non-programmers on the team asked me to define "beautiful code". I have two main criteria: 1) does it work? 2) is it easy to edit while keeping it working? When people say "code is read far more than it is written", I usually disagree: the main reason I read code is when I have to edit it! If it is working fine, it disappears into the background. But when there's a bug, I read it... as a means to the end of fixing the bug, which means editing it. So, technically, sure I'll agree it is read more than it is written, but code is rarely actually written just once. It needs to get edited for bug fixes, new features, and changing external requirements. How does that relate here? Take your ASCII table above and fix a misspelled word in the upper left cell. If you wrote "mispelled" instead of "misspelled", you just need to add the missing 's'.... and then go back and add spaces and/or dashes on each and every row to line the '|' column back up. In CS terms, it turned a constant-time edit into a O(n) operation, scaling linearly with the number of rows. But it isn't even the number of rows in the table, it is the number of rows in the source text, which can really explode when you need to elaborate in the table somehow: +-----------------------+ | This header | This | | needed three | does | | rows to fit. | not. | +==============+========+ | Here's some | More! | | text. | | +--------------+--------+ Let's add another word. +-----------------------+ | This header | This | | needed three | does | | more rows to | not. | | fit. | | +==============+========+ | Here's some | More! | | text. | | +--------------+--------+ Adding a 5-character word there took me *29* edit operations, not counting navigation of the caret. Now, maybe you use some editor macros to clean it up instead of doing it manually, but I don't have those... and if you need a fancy editor macro to just add a word to a comment, I think the comment syntax has failed. And how do you add a code sample inside the table? Oh I don't even want to try that. And let me emphasize this: this is comment in source code. If you want to read it as an end user, you can render it to HTML or whatever. In the source code, if you are reading it there... again, it is probably because you are editing it! Now, if a 5-character insertion requires 29 edit operations, what do you think the programmer is going to do? Keep up with it, or let the documentation stay slightly suboptimal and out-of-date because it is a hassle? So, that syntax is nice for little tables that get trivial edits, but for larger info tables, I prefer writing it out as paragraphs some how. That's why adrdox also supports "table_rows" and "table_columns", which I borrowed from Python's restructured text. It is basically a vertical list - similar to Markdown's nested list syntaxes - of rows and columns, or columns and rows. See more of my stuff here: http://dpldocs.info/experimental-docs/adrdox.syntax.html#tables I don't love it all, but for the most part, I implement it because it is useful to me and I at least don't hate it (or because I was forced to for Phobos compatibility lol). So my above thing becomes: * + This header needed three more rows to fit. + This does not * - Here's some text. - More! So each * introduces a new row (or column, these must be bracketed to tell which style it is), then + introduces a table header, and - introduces a table cell. Alignment is trivial now, since it is just leading indentation (and that's optional, but to be fair, actually aligning the pipes is optional in Markdown's tables too, but if you don't it gets ugly anyway in both cases). Adding a new word there? Constant time operation again. Adding a code sample is simple too, you can write it vertically like any other. And it isn't quite as beautiful as the ASCII table for some cases... but it is still very legible in plain text source view, while being infinitely easier to edit. BTW this is my big justification for bracketed syntax: putting $(SMALL_TABLE) or $(TABLE_ROWS) or $(LIST) around those bullets tells the parser not only that you are intentionally opting into special syntax, but also tells it exactly how to interpret it. So we can reuse these simple bullet-point lists in the source for a couple different render modes.
 Yeah, I'm not really a fan of *...* or _..._ in markdown 
 syntax. It's just too easy to mix them up / misidentify them 
 for identifiers in code or expressions, esp. if C-like pointer 
 dereference syntax is used. Though I suppose that's what `...` 
 is for.
Yes, the `...` stuff handles that, but is also just bugs me because when I write something like *foo* I actually DO intend for it to be rendered as *foo*, not as bold foo. For example, I like to text my friends "*hugs*". It kills me when that gets bolded. (yes, i know i can write \*hugs\* but barf.) Granted, I'm not frequently writing *hugs* in technical documentation, but the principle bugs me. Every time something like Facebook bolds my hugs it makes me hate markdown a little bit more.
  If I had my way, I would just write a normal comment as 
 opposed to a doc comment.
Ironically, ddoc was supposed to be that. https://dlang.org/spec/ddoc.html [quote] D's goals for embedded documentation are: It looks good as embedded documentation, not just after it is extracted and processed. It's easy and natural to write, i.e. minimal reliance on <tags> and other clumsy forms one would never see in a finished document. [/quote] BTW, I also hate any syntax that requires editing every line. Again, it goes back to that linear vs constant time edit. I just copy/pasted that from the website. Using bbcode or html or ddoc or adrdox, you just surround it with some tag like I did there. Even indenting it is not really necessary to make it legible and functional (though like every editor makes that simple anyway). I prefer markdown's ``` blocks to the leading for spaces primarily for this reason, though adding language tags is a secondary benefit to that. This is also why I friggen hate comments with leading stars: /* * why write all * this leading crap? */ /* This is so much better */ Edit those without using editor macros. Barf. And if you are willing to use editor macros, the other justification for it - making the comment look different than code - disappears since if your editor is fancy enough to understand that leading * crap and automatically reformat it, it could just as well syntax highlight it in some way (including displaying leading stars without saving them to the file!)
 I wouldn't expect `...` to produce a link; it should just be 
 formatted differently (typically in monospace font) to indicate 
 that it's a code snippet.
yeah me too. Though ddox for a while syntax highlighted them too. And adrdox did too for a while, with $(D) though not `` since D is explicitly D language (though phobos authors frequently used it for non-D...) though I changed my mind on it after using it - it just distracted from the text instead of adding to it.
 Using [...] syntax for links makes more sense to me, even 
 though personally, I really prefer to just write plain ole text 
 and paste the URL in its own indented block:

 	http://example.nowhere.edu/blah/blah/blah
adrdox recognizes urls and I like writing them like that when I actually write a url.... but the benefit of [reference] is that it doesn't require an actual url. It is just a symbol, in scope even. /** See also: [otherFunction] */ void foo() {} /** See also: [foo] */ void otherFunction() {} It knows those are local symbols so it looks them up in scope. adrdox understands D's import rules and even handles nested names. Having to get a URL there is a big hassle... what if a library gets a new fork/maintainer and the doc url changes? What if you want to render it offline? What a pain!
Jan 31
next sibling parent reply Seb <seb wilzba.ch> writes:
On Thursday, 1 February 2018 at 01:23:38 UTC, Adam D. Ruppe wrote:
 Now, if a 5-character insertion requires 29 edit operations, 
 what do you think the programmer is going to do? Keep up with 
 it, or let the documentation stay slightly suboptimal and 
 out-of-date because it is a hassle?
To be fair, I feel with you and all the tables I have created are formatted as good as DDoc allows, e.g. https://github.com/dlang/phobos/blob/master/std/exception.d Actually I prefer doing tables in Ddoc because it's a little easier (if you know all the macros)
 BTW, I also hate any syntax that requires editing every line. 
 Again, it goes back to that linear vs constant time edit. I 
 just copy/pasted that from the website. Using bbcode or html or 
 ddoc or adrdox, you just surround it with some tag like I did 
 there. Even indenting it is not really necessary to make it 
 legible and functional (though like every editor makes that 
 simple anyway).

 I prefer markdown's ``` blocks to the leading for spaces 
 primarily for this reason, though adding language tags is a 
 secondary benefit to that.

 This is also why I friggen hate comments with leading stars:

 /*
  * why write all
  * this leading crap?
  */

 /*
     This is so much better
 */
Same here. We recently added this to the DStyle: https://dlang.org/dstyle.html#phobos_documentation https://github.com/dlang/dlang.org/pull/2129 So, new Phobos code will be written without stars.
 Edit those without using editor macros. Barf. And if you are 
 willing to use editor macros, the other justification for it - 
 making the comment look different than code - disappears since 
 if your editor is fancy enough to understand that leading * 
 crap and automatically reformat it, it could just as well 
 syntax highlight it in some way (including displaying leading 
 stars without saving them to the file!)

 I wouldn't expect `...` to produce a link; it should just be 
 formatted differently (typically in monospace font) to 
 indicate that it's a code snippet.
It tells quite a bit about the complexity of Ddoc that I had to add support for -D to run.dlang.io ...
 Using [...] syntax for links makes more sense to me, even 
 though personally, I really prefer to just write plain ole 
 text and paste the URL in its own indented block:

 	http://example.nowhere.edu/blah/blah/blah
adrdox recognizes urls and I like writing them like that when I actually write a url.... but the benefit of [reference] is that it doesn't require an actual url. It is just a symbol, in scope even.
I'm not a fan of Ddoc by any means, but that has been fixed in Ddoc does this too now: https://run.dlang.io/is/75Z55o https://github.com/dlang/dmd/pull/7043
Jan 31
next sibling parent reply ag0aep6g <anonymous example.com> writes:
On 02/01/2018 07:18 AM, Seb wrote:
 It tells quite a bit about the complexity of Ddoc that I had to add 
 support for -D to run.dlang.io ...
[...]
 I'm not a fan of Ddoc by any means, but that has been fixed in Ddoc does 
 this too now: https://run.dlang.io/is/75Z55o
Uhh, is it a good idea to generate documentation on run.dlang.io? Isn't this an open invitation for XSS? Simple example, one can replace all links on the page with malicious ones: https://run.dlang.io/is/wYLpVx
Feb 01
parent Seb <seb wilzba.ch> writes:
On Thursday, 1 February 2018 at 14:51:41 UTC, ag0aep6g wrote:
 On 02/01/2018 07:18 AM, Seb wrote:
 It tells quite a bit about the complexity of Ddoc that I had 
 to add support for -D to run.dlang.io ...
[...]
 I'm not a fan of Ddoc by any means, but that has been fixed in 
 Ddoc does this too now: https://run.dlang.io/is/75Z55o
Uhh, is it a good idea to generate documentation on run.dlang.io? Isn't this an open invitation for XSS? Simple example, one can replace all links on the page with malicious ones: https://run.dlang.io/is/wYLpVx
I don't think it's a big problem as user needs to explicitly approve the code by hitting Run. Also all the other Web editors (JSBin, JSFiddle etc.) allow you to do the same and even load the HTML + JS when you open the page. Nevertheless, I added the "sandbox" feature of IFrames: https://www.html5rocks.com/en/tutorials/security/sandboxed-iframes -> now even any kind of JS code can't be executed. Thanks!
Feb 02
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 1 February 2018 at 06:18:52 UTC, Seb wrote:
 To be fair, I feel with you and all the tables I have created 
 are formatted as good as DDoc allows, e.g.
Yeah, that's not bad, really. I think that's actually significantly better than the Markdown table syntax - adding a new function or category there is pretty easy and it is legible enough in the source.
 Same here.
 We recently added this to the DStyle:
Yeah, I saw. Actually, I saw a debate over /** */ vs /++ +/ too, and I'm pretty firmly on the /++ +/ side of it. Almost every time I write docs and do /** or even ///, I regret it because I want to change it to /++ later anyway so I can have commented code samples in the docs.
 I'm not a fan of Ddoc by any means, but that has been fixed in 
 Ddoc does this too now: https://run.dlang.io/is/75Z55o
Well, the url recognition is nice, but my main point there was actually that xrefs ideally aren't urls at all for a few reasons. But still, it is better than nothing, no doubt.
Feb 01
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 01, 2018 at 05:33:21PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Thursday, 1 February 2018 at 06:18:52 UTC, Seb wrote:
 To be fair, I feel with you and all the tables I have created are
 formatted as good as DDoc allows, e.g.
Yeah, that's not bad, really. I think that's actually significantly better than the Markdown table syntax - adding a new function or category there is pretty easy and it is legible enough in the source.
I still prefer Markdown table syntax. But then again, I hardly ever need to put tables in my ddocs anyway, so perhaps that's just an uninformed opinion.
 [...] Actually, I saw a debate over /** */ vs /++ +/ too, and I'm
 pretty firmly on the /++ +/ side of it. Almost every time I write docs
 and do /** or even ///, I regret it because I want to change it to /++
 later anyway so I can have commented code samples in the docs.
[...] I actually like the /** */ syntax, with the stars that horrify you so much. :-D Mainly because vim automatically formats them for me, so I never actually have to fiddle with the stars myself, and I do like long block comments being clearly standing out from the rest of the code. As far as nested comments are concerned, I'm a firm believer in ddoc'd unittests, so I hardly ever bother with inline code examples, much less ones that need comments, and pretty much never ones that need block comments. I do agree about ///, though. Except for `/// ditto`, I almost invariably regret writing /// anywhere because they almost always need to be expanded into /** */ later on. They're convenient for when I'm too lazy to write docs for enum members, but when polishing up docs, they basically always need to turn into /** */. So they're good for laziness, but not much more. T -- "Computer Science is no more about computers than astronomy is about telescopes." -- E.W. Dijkstra
Feb 01
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 1 February 2018 at 19:21:52 UTC, H. S. Teoh wrote:
 As far as nested comments are concerned, I'm a firm believer in 
 ddoc'd unittests, so I hardly ever bother with inline code 
 examples, much less ones that need comments, and pretty much 
 never ones that need block comments.
I use the documented unittests too, but they do have some pretty big limits: it is hard to embed them around explanatory text and actually using them as tests has a few limits: * the unittest is not fully isolated, but users will copy/paste them into separate code. It may pass the test because of, for example, an import outside the test, but then fail to compile for the end user. * automated tests are designed for automation and resiliancy, but good examples are designed for interactivity and tinkering by the user. They are almost opposite in purpose! (even the above goes in - a unittest tests a unit... a good example shows how to put the pieces together) * unittests with a main function are a little wonky, but you can make it work. I still kinda like it... but I think it is actually overrated.
Feb 02
prev sibling parent reply Kagamin <spam here.lot> writes:
On Thursday, 1 February 2018 at 01:23:38 UTC, Adam D. Ruppe wrote:
 In CS terms, it turned a constant-time edit into a O(n) 
 operation, scaling linearly with the number of rows.
Well, there's line-oriented tabular data format, forgot the name (re*-something), it looks like definition list: --- Member: front Description: gets front element Member: popFront Description: pops front element Member: empty Description: checks if empty --- Is logically a table: |Member |Description| +--------+-----------+ |front |gets front element| +--------+---------- |popFront|pops front element| +--------+---------- |empty |checks if empty| --------------------
Feb 01
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 1 February 2018 at 12:06:44 UTC, Kagamin wrote:
 Well, there's line-oriented tabular data format, forgot the 
 name (re*-something), it looks like definition list:
What bugs me with that sample is that the headers are repeated a lot... but it isn't bad. But re* sounds like maybe restructuredText which I borrowed some ideas from too.
Feb 02
parent Kagamin <spam here.lot> writes:
On Friday, 2 February 2018 at 15:04:42 UTC, Adam D. Ruppe wrote:
 What bugs me with that sample is that the headers are repeated 
 a lot... but it isn't bad.
Yeah, the moment I scrolled the table header out of sight I can't make sense of the cells anymore.
 But re* sounds like maybe restructuredText which I borrowed 
 some ideas from too.
Ah, found, it's called recfile https://www.gnu.org/software/recutils/
Feb 03
prev sibling next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/31/18 5:55 PM, Adam D. Ruppe wrote:

 Now though, inline code like $(D) and $(REF) are ambiguous. They are 
 short enough that they'd normally fall into my "ok with it" zone like 
 $(B)... but they are also so common and I want to encourage their use. 
 And having three shifted characters that must appear in order is kinda 
 painful to type - it just breaks up the thought process, and can get 
 somewhat weird to look at.
Where it breaks down is when you have many nested tags, and you end with ))))) I hate that. I've seen many bugs in the D documentation because of that. I'd rather we use different delimeters for different tags, like markdown. -Steve
Jan 31
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient. With Ddoc, I do this at the opening (, and see if the matching one is the closing ). If not, surprisingly, the match shown is the one that is erroneous. https://github.com/DigitalMars/med/blob/master/src/med/search.d#L453
Jan 31
next sibling parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Wednesday, January 31, 2018 18:58:29 Walter Bright via Digitalmars-d 
wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end with
 )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient. With Ddoc, I do this at the opening (, and see if the matching one is the closing ). If not, surprisingly, the match shown is the one that is erroneous. https://github.com/DigitalMars/med/blob/master/src/med/search.d#L453
vim does that and it's invaluable. It also makes it easy to hop between matching parens or braces, which is part of what drives me nuts about python. Because it doesn't have braces, it's harder to hop to the opposite end of a block. Now, I think that it's still problematic when you end up with a bunch of parens in a row, since you tend to have to put your study it and put your cursor on each paren to understand what you're looking at, but having that highlighting definitely helps. - Jonathan M Davis
Jan 31
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end 
 with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter. When I'm reviewing a PR, I don't see the matching as easily. Even with an editor tool, it's a lot of parentheses to look at. An example: https://github.com/dlang/phobos/pull/5452 Introduced: https://github.com/dlang/phobos/pull/4027 Take a look at the original PR and see how the parentheses look fine, very very hard to see that there is a problem. -Steve
Feb 01
next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 01, 2018 at 09:09:28AM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
 On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you
 end with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.
Yeah, vim has had this *by default* since who knows how long ago. I've been surprised that things like this still bother people today -- non-vim users are missing out!
 When I'm reviewing a PR, I don't see the matching as easily. Even with
 an editor tool, it's a lot of parentheses to look at.
[...] This is one reason I'm not a fan of browser-based tools. They're essentially just 90's technology in fancy dress. For reviewing complicated PRs, I still prefer just fetching the git branch directly into my local Phobos fork and using vim to look through the code. Seb's git scripts for fetching/pushing PRs is pretty useful for this; see the Maintainer's guidelines page on the wiki. T -- Valentine's Day: an occasion for florists to reach into the wallets of nominal lovers in dire need of being reminded to profess their hypothetical love for their long-forgotten.
Feb 01
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:
 On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.
The #if too?
 When I'm reviewing a PR, I don't see the matching as easily.
True, but that applies to anything with a block structure.
Feb 02
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 2/2/18 7:10 PM, Walter Bright wrote:
 On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:
 On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end 
 with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.
The #if too?
Yes. http://vim.wikia.com/wiki/Moving_to_matching_braces
 When I'm reviewing a PR, I don't see the matching as easily.
True, but that applies to anything with a block structure.
Sure, I also have a difficult time with loads of parentheses in function calls too. I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line. Note: if there are brace issues, the auto-tester fails it. Why did that example I posted not catch the extra closing paren? Can we have it do so? -Steve
Feb 04
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
[...]
 I don't have a hard time with braces. It tends to be worse with
 parentheses.  Generally these are indented properly, and not }}}}} all
 on one line.
Wait till you see Lisp code. :-P
 Note: if there are brace issues, the auto-tester fails it. Why did
 that example I posted not catch the extra closing paren? Can we have
 it do so?
[...] Ddoc does complain about it, though it seems it's not treated as a compile error. It's probably just a matter of making the autotester parse the compiler output to look for these error/warning messages, and forcing a test failure if found. T -- Without geometry, life would be pointless. -- VS
Feb 04
next sibling parent Seb <seb wilzba.ch> writes:
On Monday, 5 February 2018 at 06:27:02 UTC, H. S. Teoh wrote:
 On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer 
 via Digitalmars-d wrote: [...]
 I don't have a hard time with braces. It tends to be worse 
 with parentheses.  Generally these are indented properly, and 
 not }}}}} all on one line.
Wait till you see Lisp code. :-P
 Note: if there are brace issues, the auto-tester fails it. Why 
 did that example I posted not catch the extra closing paren? 
 Can we have it do so?
[...] Ddoc does complain about it, though it seems it's not treated as a compile error. It's probably just a matter of making the autotester parse the compiler output to look for these error/warning messages, and forcing a test failure if found.
Yeah DMD emits those warnings and until recently -w with warnings didn't even result in DMD terminating with a non-zero exit code, though we finally fixed that a few weeks ago and 2.079 will finally behave as expected: https://github.com/dlang/dmd/pull/7440 Also note that you can't check-in any code in the core repositories with failing Ddoc messages. This was checked for Phobos for a long time, while again for DMD and druntime that was only added recently, e.g.: https://github.com/dlang/dmd/pull/7432
Feb 04
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 2/5/18 1:27 AM, H. S. Teoh wrote:
 On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
 [...]
 I don't have a hard time with braces. It tends to be worse with
 parentheses.  Generally these are indented properly, and not }}}}} all
 on one line.
Wait till you see Lisp code. :-P
I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful. -Steve
Feb 05
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Feb 05, 2018 at 09:50:38AM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
 On 2/5/18 1:27 AM, H. S. Teoh wrote:
 On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via
Digitalmars-d wrote:
 [...]
 I don't have a hard time with braces. It tends to be worse with
 parentheses.  Generally these are indented properly, and not }}}}}
 all on one line.
Wait till you see Lisp code. :-P
I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.
[...] Apparently it's a prevailing style for Lisp and Lisp dialects like Scheme. Random example (this is in Guile, a Scheme dialect, quoted from open source code): (define (match-predicate obj alist) (if (null? alist) "Unknown type" (if (apply (caar alist) obj) (cdar alist) (match-predicate obj (cdr alist))))) The only way I can keep my sanity while editing this sort of code is vim's jump-to-match feature. T -- "If you're arguing, you're losing." -- Mike Thomas
Feb 05
next sibling parent bachmeier <no spam.net> writes:
On Monday, 5 February 2018 at 15:27:56 UTC, H. S. Teoh wrote:
 On Mon, Feb 05, 2018 at 09:50:38AM -0500, Steven Schveighoffer 
 via Digitalmars-d wrote:
 On 2/5/18 1:27 AM, H. S. Teoh wrote:
 On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven 
 Schveighoffer via Digitalmars-d wrote: [...]
 I don't have a hard time with braces. It tends to be worse 
 with parentheses.  Generally these are indented properly, 
 and not }}}}} all on one line.
Wait till you see Lisp code. :-P
I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.
[...] Apparently it's a prevailing style for Lisp and Lisp dialects like Scheme. Random example (this is in Guile, a Scheme dialect, quoted from open source code): (define (match-predicate obj alist) (if (null? alist) "Unknown type" (if (apply (caar alist) obj) (cdar alist) (match-predicate obj (cdr alist))))) The only way I can keep my sanity while editing this sort of code is vim's jump-to-match feature. T
It's common in Scheme/Racket to use square brackets for nested terms: (let ([x (random 4)] [o (random 4)]) (cond [(> x o) "X wins"] [(> o x) "O wins"] [else "cat's game"])) I find code written like your example (which is unfortunately quite common) to be no different from poorly-written Perl code. Properly indented and square bracketed Scheme code is easy to read. One of the nice things about D IMO is that you have to work harder to write ugly code. Atrocities like chaining a bunch of function calls together don't look bad in D.
Feb 05
prev sibling parent Timon Gehr <timon.gehr gmx.ch> writes:
On 05.02.2018 16:27, H. S. Teoh wrote:
 
 Apparently it's a prevailing style for Lisp and Lisp dialects like
 Scheme.  Random example (this is in Guile, a Scheme dialect, quoted from
 open source code):
 
 	(define (match-predicate obj alist)
 	  (if (null? alist)
 	      "Unknown type"
 	      (if (apply (caar alist) obj)
 		  (cdar alist)
 		  (match-predicate obj (cdr alist)))))
 
 The only way I can keep my sanity while editing this sort of code is
 vim's jump-to-match feature.
I additionally use: https://www.emacswiki.org/emacs/RainbowDelimiters
Feb 05
prev sibling parent reply Patrick Schluter <Patrick.Schluter bbox.fr> writes:
On Monday, 5 February 2018 at 14:50:38 UTC, Steven Schveighoffer 
wrote:
 On 2/5/18 1:27 AM, H. S. Teoh wrote:
 On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer 
 via Digitalmars-d wrote:
 [...]
 I don't have a hard time with braces. It tends to be worse 
 with
 parentheses.  Generally these are indented properly, and not 
 }}}}} all
 on one line.
Wait till you see Lisp code. :-P
I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.
When I programmed AutoLISP extension in AutoCAD I would use parentheses in the exact same way as I use { } in C. So not at the end of a line but vertically at the level of indentation; (defun xy (car (cdr (cons a b) ) ) ) This made it much better to handle.
Feb 05
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Feb 05, 2018 at 06:38:22PM +0000, Patrick Schluter via Digitalmars-d
wrote:
[...]
 When I programmed AutoLISP extension in AutoCAD I would use
 parentheses in the exact same way as I use { } in C. So not at the end
 of a line but vertically at the level of indentation;
 
     (defun xy
       (car
          (cdr
             (cons a b)
          )
       )
     )
 
 This made it much better to handle.
That's also my personal preference. Unfortunately, such practice is frowned upon by some Scheme communities. Why, is absolutely beyond me. :-D T -- LINUX = Lousy Interface for Nefarious Unix Xenophobes.
Feb 05
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 2/4/2018 11:34 AM, Steven Schveighoffer wrote:
 On 2/2/18 7:10 PM, Walter Bright wrote:
 On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:
 On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you end with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.
The #if too?
Yes. http://vim.wikia.com/wiki/Moving_to_matching_braces
So I see. I wonder when that was added to vim. I put it in MicroEmacs in the late 1980s, and vi definitely didn't have it then. I didn't put in Pascal begin/end, because I didn't care for Pascal :-)
Feb 04
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 2/5/18 2:53 AM, Walter Bright wrote:
 On 2/4/2018 11:34 AM, Steven Schveighoffer wrote:
 On 2/2/18 7:10 PM, Walter Bright wrote:
 On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:
 On 1/31/18 9:58 PM, Walter Bright wrote:
 On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
 Where it breaks down is when you have many nested tags, and you 
 end with )))))
Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.
This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.
The #if too?
Yes. http://vim.wikia.com/wiki/Moving_to_matching_braces
So I see. I wonder when that was added to vim. I put it in MicroEmacs in the late 1980s, and vi definitely didn't have it then. I didn't put in Pascal begin/end, because I didn't care for Pascal :-)
I should clarify -- the matching parentheses feature has been in vim forever (note -- vim didn't exist in the last 80s, straight vi I think doesn't have these features). I don't know how long the matching #if/#endif feature has been there, I haven't used it much. A nice feature of this is that the "jump to match" command is like any other move command in vim -- you can hook it to copy/pasting, deleting, formatting, etc. It's very useful. But this is a bit off topic :) -Steve
Feb 05
prev sibling parent reply Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Wednesday, January 31, 2018 16:19:53 H. S. Teoh via Digitalmars-d wrote:
 In general, almost all text macro / formatting systems, from LaTeX to
 HTML to ddoc, are universally ugly and verbose when it comes to tables,
 and makes my eyes bleed. The only exception I've found so far is

 markdown, where you can actually write this:
   |Blah|Blah|
   |----|----|
   |abc |def |
   |ghi |jkl |

 It's not perfect, but it's worlds better than the line noise syntax of
 the alternatives.
Yeah. Tables are generally ugly, though they're also not super-common in documentation - perhaps enough to be annoying, but most functions don't have them.
 Actually, for me it's not so much a matter of "it's faster to type";
 it's more of an issue of "when I'm reading (and presumably thinking
 (hard) about) source code, do I really want to expend the mental
 resources to parse the syntax of yet another embedded DSL inside a
 *comment*?".  If I had my way, I would just write a normal comment as
 opposed to a doc comment.  What makes the doc proposition attractive is
 that, in an ideal world, a "normal" comment can be automatically
 translated into nice docs without needing to pepper-spray it with
 foreign syntax particles, so that I can read the comment while working
 on the code, in addition to having nice docs to show to others in a
 format they prefer, like HTML or whatever.

 That's why I would actually welcome markdown-like syntax in ddoc. Yeah,
 it has limitations and sux in many ways, but IMNSHO you shouldn't be
 reimplementing complex HTML syntax inside a doc comment anyway -- leave
 that to an external templating engine or whatever you wish to use, and
 just let the doc comment be as readable as possible *as source code*.
Personally, I hate markdown, because it makes certain syntax magical - e.g. it's not uncommon that a commit message ends up looking bad when github uses it as the message for a PR, because some piece of code contained * or some other piece of syntax that markdown decides to do something magical with. I _much_ prefer the explicit syntax used by ddoc, so I can't say that I'm at all happy at the idea of markdown syntax being added to ddoc. Ddoc is by no means perfect, but I don't see adding magical syntax as being a particular nice fix. Clearly, there's some disagreement on that front however. Personally, I actually like the fact that the website is done in ddoc, and while sometimes it looks ugly in the documentation, it mostly looks just fine. IMHO, the main problem with ddoc for documentation is that it doesn't automatically handle stuff like cross-links, and it fundamentally can't, because to do that properly, you have to generate all of the docs at once with a standard layout for where everything goes so that the links can link to stuff. To get it right, the compiler would have to actually act like a documentation generator and not just like it's compiling a file to ddoc. - Jonathan M Davis
Jan 31
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis 
wrote:
 Personally, I hate markdown, because it makes certain syntax 
 magical - e.g. it's not uncommon that a commit message ends up 
 looking bad when github uses it as the message for a PR, 
 because some piece of code contained * or some other piece of 
 syntax that markdown decides to do something magical with.
Yeah.
 I _much_ prefer the explicit syntax used by ddoc, so I can't 
 say that I'm at all happy at the idea of markdown syntax being 
 added to ddoc.
I agree, which is why adrdox only has a few magic syntaxes at top level and they are in places where I think it is more important to be extremely convenient (like cross-linking*). But, at the same time, some special syntax can be REALLY nice. So I went with the hybrid approach: certain ddoc macro blocks actually run magic syntax: $(LIST * List item here * another list item * third list item ) The bracket clearly indicates that you want to opt-in to the special syntax, then you get to use that syntax for a while for the convenience. Another benefit is you can add other tweaks like class names for the HTML inside the bracket since there is a spot for that. But anyway, the bracket also lets me use different syntaxes or reuse the same in a few places and generate different things. And BTW it is worth noting that ddoc ALREADY has a little bit of this: see the "Params:" section! * BTW I almost wanted that syntax to be a bit uglier so you can embed it in code samples too unambiguously but that made me use it less instead of more...
 IMHO, the main problem with ddoc for documentation is that it 
 doesn't automatically handle stuff like cross-links, and it 
 fundamentally can't, because to do that properly, you have to 
 generate all of the docs at once with a standard layout for 
 where everything goes so that the links can link to stuff.
Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it. Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.
Feb 02
next sibling parent Jonathan M Davis <newsgroup.d jmdavisprog.com> writes:
On Friday, February 02, 2018 15:12:45 Adam D. Ruppe via Digitalmars-d wrote:
 On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
 IMHO, the main problem with ddoc for documentation is that it
 doesn't automatically handle stuff like cross-links, and it
 fundamentally can't, because to do that properly, you have to
 generate all of the docs at once with a standard layout for
 where everything goes so that the links can link to stuff.
Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it. Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.
I thought about that, but it falls flat on its face as soon as not all of the user-defined types are from the library being documented. The simplest example would be if I were to publish my own library but it used types from Phobos in its API. Turning those types into links would then try to link to my project's documentation, which wouldn't work. Best case, I could create redirects to the Phobos docs, so that might work, but it gets messy fast, and any types from 3rd party libraries which were used in the API would have the same problem. Somehow, the links would have to be made to work regardless of whether the types were part of the project being documented. - Jonathan M Davis
Feb 02
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Feb 02, 2018 at 10:49:18AM -0700, Jonathan M Davis via Digitalmars-d
wrote:
 On Friday, February 02, 2018 15:12:45 Adam D. Ruppe via Digitalmars-d wrote:
 On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
 IMHO, the main problem with ddoc for documentation is that it
 doesn't automatically handle stuff like cross-links, and it
 fundamentally can't, because to do that properly, you have to
 generate all of the docs at once with a standard layout for where
 everything goes so that the links can link to stuff.
Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it. Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.
I thought about that, but it falls flat on its face as soon as not all of the user-defined types are from the library being documented. The simplest example would be if I were to publish my own library but it used types from Phobos in its API. Turning those types into links would then try to link to my project's documentation, which wouldn't work. Best case, I could create redirects to the Phobos docs, so that might work, but it gets messy fast, and any types from 3rd party libraries which were used in the API would have the same problem. Somehow, the links would have to be made to work regardless of whether the types were part of the project being documented.
[...] In an ideal world, you wouldn't need to encode any of this stuff inside a ddoc comment. Since ddoc comments are processed by the compiler, and the compiler has all of the information necessary to resolve identifiers, arguably all that *should* be needed is just a way to indicate in the docs, "this word is an identifier", and the compiler would figure out what it's referring to, perhaps expand it into a fully-qualified name like std.range.primitives.isInputRange. Then this can be handed to a stylesheet that would turn it into a link of some sort. Cluttering ddoc comments with URLs (or, as a proxy, macros containing information specific to URLs) that, arguably, the code itself shouldn't depend on, is something I have ideological issues with. It's one thing to refer to a full URL to some online reference like a technical spec that's unchanging and, ostensibly, will always be out there; it's quite something else to explicitly spell out links to a particular symbol using a hard-coded path that can change any time. E.g., today I may link to MyType as: $(LINK $(WEBROOT)/mypackage/mymod.html#MyType) but tomorrow I may have a major refactoring and now I have to change *all* such links to: $(LINK $(WEBROOT)/mynewpackage/newsubpackage/newmod.html#MyType) instead, whereas the code itself actually doesn't need to change at all, because the compiler already knows where's the new location of the symbol, using standard identifier resolution. Why can't I just write `[MyType]` (or whatever other syntax you prefer), and let the compiler figure out what the right fully-qualified name is? Once the compiler figures it out, the stylesheet takes care of turning it into a HTML link or the equivalent in whatever other output format you may be using. On a higher level, even explicit links to symbols in Phobos docs are a bad idea. What if 5 months later we decide to move dlang.org/phobos to dlang.org/docs/phobos? Or if a Phobos refactoring moves a symbol to another module? Any explicit URLs in user ddoc comments will break, and will have to be updated *one-by-one*. Whereas if we let the compiler do its job, the worst that would happen is we update the stylesheet to point to dlang.org/docs/phobos/* instead of dlang.org/phobos/*, and *all* links in generated ddocs will be automatically corrected. Any change in the path to the symbol's doc will already have been resolved by the compiler -- if your code compiles at all. tl;dr: I think anything more than plain old markup saying "this is a symbol that needs a link" in a doc comment is a bad idea. Ddoc comments shouldn't be replicating the job of the compiler, and that poorly. T -- If creativity is stifled by rigid discipline, then it is not true creativity.
Feb 02
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
 In an ideal world, you wouldn't need to encode any of this 
 stuff inside a ddoc comment.
Well, that's what the Phobos REF macro does... sort of. You write $(REF symbolName, std, module) and the macro figures out the link. Though, even that macro is based on the url structure on dlang.org... it separates package arguments because it needs to $2_$3.html#$1 which doesn't match any generator. But it is a heck of a lot better than the old way of $(LINK2 std_string.html, std.string) which is just plain broken (and btw a few of those are still there :( ).
  Since ddoc comments are processed by the compiler, and the 
 compiler has all of the information necessary to resolve 
 identifiers, arguably all that *should* be needed is just a way 
 to indicate in the docs, "this word is an identifier", and the 
 compiler would figure out what it's referring to, perhaps 
 expand it into a fully-qualified name like 
 std.range.primitives.isInputRange.
Right, this is exactly what adrdox does and it has been a smashing success to me. It'd be nice if ddoc did it too (at least so I don't have to deal with so many merge conflicts on the broken phobos source links!)
Feb 02
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Feb 02, 2018 at 07:46:51PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
 In an ideal world, you wouldn't need to encode any of this stuff
 inside a ddoc comment.
Well, that's what the Phobos REF macro does... sort of. You write $(REF symbolName, std, module) and the macro figures out the link. Though, even that macro is based on the url structure on dlang.org...
[...] Well exactly, and that's the problem. The macro arguments require knowledge of the URL structure on dlang.org. And also knowledge of the FQN of the symbol. When the FQN changes, you have to update *every link* that refers to that symbol. That's like coding in the bad ole days before encapsulation was a common practice. Everything depended on everything else, and changing one small thing causes a ripple effect that requires touching the rest of the code in 100 different places. We should be leveraging what the compiler is already capable of doing, and keep the docs agnostic of the nitty-gritty details of the symbol's FQN or where it might reside in the URL tree. It's plain and simple encapsulation, as applied to docs. [...]
  Since ddoc comments are processed by the compiler, and the compiler
  has all of the information necessary to resolve identifiers,
  arguably all that *should* be needed is just a way to indicate in
  the docs, "this word is an identifier", and the compiler would
  figure out what it's referring to, perhaps expand it into a
  fully-qualified name like std.range.primitives.isInputRange.
Right, this is exactly what adrdox does and it has been a smashing success to me. It'd be nice if ddoc did it too (at least so I don't have to deal with so many merge conflicts on the broken phobos source links!)
[...] This is the kind of thing you should be promoting to Andrei to convince him that dpldocs is better. ;-) T -- Today's society is one of specialization: as you grow, you learn more and more about less and less. Eventually, you know everything about nothing.
Feb 02
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:
 This is the kind of thing you should be promoting to Andrei to 
 convince him that dpldocs is better. ;-)
I've laid out my arguments several times, including this point. Actually, $(REF) was introduced after I made the argument, so it is a slight win, though ddoc, over the last two years, has barely caught up to what I was able to accomplish independently in two weeks.
Feb 02
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:
 This is the kind of thing you should be promoting to Andrei to 
 convince him that dpldocs is better. ;-)
I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.
 b905180b1fffa78f922677ee90ed8ae9b803fc4f
My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)
Feb 02
next sibling parent reply Seb <seb wilzba.ch> writes:
On Saturday, 3 February 2018 at 04:37:44 UTC, Adam D. Ruppe wrote:
 On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:
 This is the kind of thing you should be promoting to Andrei to 
 convince him that dpldocs is better. ;-)
I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.
 b905180b1fffa78f922677ee90ed8ae9b803fc4f
My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)
I think that would only work if we drop the ddoc of phobos entirely or add a similar feature to ddoc. Don't get me wrong, I like adrdox a lot more than ddoc and I don't like the REF Ddoc feature either.
Feb 03
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 3 February 2018 at 11:41:27 UTC, Seb wrote:
 I think that would only work if we drop the ddoc of phobos 
 entirely or add a similar feature to ddoc.
I could live with either :P But the underscore thing is just plain bad. Literally NOBODY has ever liked it - every time this comes up, people are not happy with it saying "why is my word randomly italicized" and "why do i have to put _ randomly in phobos". Just even such an OBVIOUS GLARING FLAW with a reasonably straightforward replacement path (define the highlight macro to be a no-op, minimally, or just simply remove the "feature" entirely with a transition switch to warn you every time it sees what is now an extra _ on a word - that's what I did with adrdox and fixed my Phobos fork up in about 30 mins) hits a brick wall.
 Don't get me wrong, I like adrdox a lot more than ddoc and I 
 don't like the REF Ddoc feature either.
BTW I am going to have another burst of time to do improvements to it soon, and I think I still have a list of nits from you so you might see some nice improvements in the coming month. February is a somewhat slow month for me with day job work which means I expect to be able to afford a good block of time to work on this again.
Feb 03
prev sibling next sibling parent reply Seb <seb wilzba.ch> writes:
On Saturday, 3 February 2018 at 04:37:44 UTC, Adam D. Ruppe wrote:
 On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:
 This is the kind of thing you should be promoting to Andrei to 
 convince him that dpldocs is better. ;-)
I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.
 b905180b1fffa78f922677ee90ed8ae9b803fc4f
My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)
Have you thought of simply postprocessing REF_ALTTEXT for your documentation engine for now? That won't lead to merge conflicts ;-) e.g. sed -i "s/[$](REF_ALTTEXT \([^,]*\),\([^,]*\),[^)]*)/[\2|\1]" **/*.d
Feb 03
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 3 February 2018 at 11:44:44 UTC, Seb wrote:
 Have you thought of simply postprocessing REF_ALTTEXT for your 
 documentation engine for now?
It actually supports the macro, so I could just keep the upstream source here, just the difference between them is kinda striking. The history here is there were a lot of broken links in the phobos source because they used LINK2 when I forked. I changed them to my [reference] syntax and made the point that if it is broken for me, it is broken for ddox too, so a macro should be introduced to fix it. After that, the $(REF) and $(REF_ALTTEXT) macros were introduced in Phobos.... but I had already changed all the LINK2 in my tree to my syntax, so when Phobos changed their LINK2s to REF later (it took between months and years for Phobos to catch up to what I was able to accomplish in days and weeks!), I added support for the Phobos macro too, but the ones I had already changed the syntax on caused these merge conflicts. I pasted it here just because of the kinda striking difference. And adrdox actually even supports pseudo-symbol references of this type so you could just write [input-range] and it'd look it up from a user-supplied glossary (located in the source of package.d btw, it is scoped just like a real symbol) to know the term and the appropriate link! But even the long form you see above is just so much nicer than the macro one. You don't have to tell the compiler something the compiler already knows - which import isInputRange comes from.
Feb 03
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sat, Feb 03, 2018 at 04:37:44AM +0000, Adam D. Ruppe via Digitalmars-d wrote:
[...]
 I'm updating my fork now and check out this merge conflict:
 
 <<<<<<< HEAD
      *  source = The [isInputRange|input range] to encode.
 =======
      *  source = The $(REF_ALTTEXT input range, isInputRange,
 std,range,primitives)
      *           to _encode.
 b905180b1fffa78f922677ee90ed8ae9b803fc4f
My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)
+1000. That misfeature has been continually plaguing us ever since it was introduced, leading to a constant endless churn of PRs sprinkling _'s everywhere just to suppress ddoc's "helpful" highlighting of stuff it shouldn't have highlighted in the first place. Extremely annoying. T -- A linguistics professor was lecturing to his class one day. "In English," he said, "A double negative forms a positive. In some languages, though, such as Russian, a double negative is still a negative. However, there is no language wherein a double positive can form a negative." A voice from the back of the room piped up, "Yeah, yeah."
Feb 03
prev sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sat, Feb 03, 2018 at 06:18:55AM -0800, H. S. Teoh via Digitalmars-d wrote:
 On Sat, Feb 03, 2018 at 04:37:44AM +0000, Adam D. Ruppe via Digitalmars-d
wrote:
 [...]
 (note that the stupid leading _ is something I strip out too. Ddoc's
 most moronic "feature". Can we PLEASE kill that?!?!?!!)
+1000. That misfeature has been continually plaguing us ever since it was introduced, leading to a constant endless churn of PRs sprinkling _'s everywhere just to suppress ddoc's "helpful" highlighting of stuff it shouldn't have highlighted in the first place. Extremely annoying.
[...] I got sick of just whining about, and decided to do something about it instead: https://github.com/dlang/dmd/pull/7834 Destroy! T -- Right now I'm having amnesia and deja vu at the same time. I think I've forgotten this before.
Feb 03
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Saturday, 3 February 2018 at 17:20:35 UTC, H. S. Teoh wrote:
 I got sick of just whining about, and decided to do something 
 about it instead:
Whelp, g'luck. I've tried to null out the macro before, maybe this approach will work better. The stupid thing should just be killed entirely though. It was never of any legitimate value.
Feb 03
parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sat, Feb 03, 2018 at 06:25:26PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Saturday, 3 February 2018 at 17:20:35 UTC, H. S. Teoh wrote:
 I got sick of just whining about, and decided to do something about
 it instead:
Whelp, g'luck. I've tried to null out the macro before, maybe this approach will work better.
This approach is more likely to be accepted. ;-)
 The stupid thing should just be killed entirely though. It was never
 of any legitimate value.
Shh! The plan is, after this PR gets merged, it becomes easier to turn off the behaviour by default as part of a PR to improve the default ddoc stylesheet. Once it's off by default, we can delete the code as "dead code". ;-P T -- The easy way is the wrong way, and the hard way is the stupid way. Pick one.
Feb 03
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 31 January 2018 at 15:40:04 UTC, Jakub Łabaj wrote:
 What is the current state of the art of writing inline code in 
 the documentation?
To give you a quick answer, the tide is going toward ``. You should probably just use it in most cases as long as the code fits on a single line. If it is a multi-line sample, use ddoc's `---` brackets or a documented unittest instead. If you do want cross referencing, don't rely on $(D) nor `` to do it. Instead, there's a $(REF) macro in std.ddoc to use. Do NOT combine them: See also: $(REF std,string,lowerCase) // correct (i think)* See also: `$(REF ...)` // wrong, do not use `` here * I don't remember the actual syntax for that ref macro.
Jan 31
next sibling parent Seb <seb wilzba.ch> writes:
On Thursday, 1 February 2018 at 01:27:43 UTC, Adam D. Ruppe wrote:
 On Wednesday, 31 January 2018 at 15:40:04 UTC, Jakub Łabaj 
 wrote:
 What is the current state of the art of writing inline code in 
 the documentation?
To give you a quick answer, the tide is going toward ``. You should probably just use it in most cases as long as the code fits on a single line. If it is a multi-line sample, use ddoc's `---` brackets or a documented unittest instead. If you do want cross referencing, don't rely on $(D) nor `` to do it. Instead, there's a $(REF) macro in std.ddoc to use. Do NOT combine them: See also: $(REF std,string,lowerCase) // correct (i think)* See also: `$(REF ...)` // wrong, do not use `` here * I don't remember the actual syntax for that ref macro.
It's: $(REF lowerCase, std,string) or $(REF_ALTTEXT alternative text, lowerCase, std,string)
Feb 01
prev sibling parent Jakub =?UTF-8?B?xYFhYmFq?= <uaaabbjjkl gmail.com> writes:
I can see that ddoc is a pretty hot topic here ;)

On Thursday, 1 February 2018 at 01:27:43 UTC, Adam D. Ruppe wrote:
 To give you a quick answer, the tide is going toward ``. You 
 should probably just use it in most cases as long as the code 
 fits on a single line. If it is a multi-line sample, use ddoc's 
 `---` brackets or a documented unittest instead.
Thank you for the answer and very thorough explanation. Seems like the Wiki contains up-to-date information then.
Feb 01