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.

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

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.

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"

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 ``.

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.

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!

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.

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

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