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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 

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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018
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 2018