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!
