## digitalmars.D - Improving ddoc

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Hello,

In wake of the recent discussions on improving ddoc syntax we're looking
at doing something about it. Please discuss any ideas you might have
here. Thanks!

One simple starter would be to allow one escape character, e.g. the
backtick (), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write MACRO arg1, arg2. Andrei  Dec 31 2014 "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes: On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO
arg1, arg2) one can write MACRO arg1, arg2.

[...]

The problem with using only a single escape character is that it's
ambiguous when nested. If you write XYZ, should it be interpreted as
$(X$(Y)) or $(X)Y$(Z)?

Also, the people complaining about $(MACRO ...)) syntax aren't complaining about the$(...) part specifically, but about the MACRO
part. No matter how you try to prettify it, $(MACRO x y z) is still MACRO x y z. As long as you have a single syntax for all macros, the syntax people won't be happy. What they are clamoring for is dedicated syntax for the most common macros, so that they don't have to keep repeating the MACRO part of the invocation. Besides, ddoc syntax is really the least of our problems right now, what with functionality issues like: https://issues.dlang.org/show_bug.cgi?id=9731 https://issues.dlang.org/show_bug.cgi?id=13270 https://issues.dlang.org/show_bug.cgi?id=13272 https://issues.dlang.org/show_bug.cgi?id=13676 just to name a few. Everyone wants a new coffee machine but nobody cares about nuclear reactor usability issues. T -- Music critic: "That's an imitation fugue!"  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: The problem with using only a single escape character is that it's ambiguous when nested. If you write XYZ, should it be interpreted as$(X $(Y)) or$(X)Y$(Z)? That issue is fairly obvious, as is its solution - backticks (or whichever escape) don't nest; for nesting use the full syntax. Just like bash/zsh. Also, the people complaining about$(MACRO ...)) syntax aren't
complaining about the $(...) part specifically, but about the MACRO part. No matter how you try to prettify it,$(MACRO x y z) is still
MACRO x y z. As long as you have a single syntax for all macros, the
syntax people won't be happy. What they are clamoring for is dedicated
syntax for the most common macros, so that they don't have to keep
repeating the MACRO part of the invocation.

That's a bit of a bummer because that seems a slippery slope to me. But
I guess we could standardize on markdown syntax.

Besides, ddoc syntax is really the least of our problems right now, what
with functionality issues like:

https://issues.dlang.org/show_bug.cgi?id=9731
https://issues.dlang.org/show_bug.cgi?id=13270
https://issues.dlang.org/show_bug.cgi?id=13272
https://issues.dlang.org/show_bug.cgi?id=13676

just to name a few. Everyone wants a new coffee machine but nobody cares
about nuclear reactor usability issues.

That's a very good point.

Andrei

Dec 31 2014
"H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 06:27:30PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote:
On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
The problem with using only a single escape character is that it's
ambiguous when nested. If you write XYZ, should it be interpreted
as $(X$(Y)) or $(X)Y$(Z)?

That issue is fairly obvious, as is its solution - backticks (or
whichever escape) don't nest; for nesting use the full syntax. Just
like bash/zsh.

So there will be two syntaxes for the same thing in the non-nested case
then?

Also, the people complaining about $(MACRO ...)) syntax aren't complaining about the$(...) part specifically, but about the MACRO
part. No matter how you try to prettify it, $(MACRO x y z) is still MACRO x y z. As long as you have a single syntax for all macros, the syntax people won't be happy. What they are clamoring for is dedicated syntax for the most common macros, so that they don't have to keep repeating the MACRO part of the invocation. That's a bit of a bummer because that seems a slippery slope to me. But I guess we could standardize on markdown syntax. Unfortunately it seems Walter is against it. But on a deeper note, perhaps the issue isn't really ddoc syntax per se, but the fact that doc comments can *only* be processed by ddoc. If there was a way to get the raw text out, the people who dislike ddoc can pipe it to the formatter of their own choice, and they would be happy. People who are indifferent will get ddoc by default, which, despite its flaws, isn't really *that* horrible. T -- Why is it that all of the instruments seeking intelligent life in the universe are pointed away from Earth? -- Michael Beibl  Dec 31 2014 "Adam D. Ruppe" <destructionator gmail.com> writes: On Thursday, 1 January 2015 at 02:43:39 UTC, H. S. Teoh via Digitalmars-d wrote: But on a deeper note, perhaps the issue isn't really ddoc syntax per se, but the fact that doc comments can *only* be processed by ddoc. If there was a way to get the raw text out There is a way: dmd -D -X gets the raw text into the .json file. That's what my dpldocs.info scans: http://dpldocs.info/std.algorithm (which is, sadly, pretty illegible for the Phobos docs, but it works for my files e.g. http://dpldocs.info/search/search2?searchTerm=arsd.dom.Element.getElementsBySelector  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes: "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> wrote: On Wed, Dec 31, 2014 at 06:27:30PM -0800, Andrei Alexandrescu via Digitalmars-d wrote: On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: The problem with using only a single escape character is that it's ambiguous when nested. If you write XYZ, should it be interpreted as$(X $(Y)) or$(X)Y$(Z)? That issue is fairly obvious, as is its solution - backticks (or whichever escape) don't nest; for nesting use the full syntax. Just like bash/zsh. So there will be two syntaxes for the same thing in the non-nested case then? Also, the people complaining about$(MACRO ...)) syntax aren't
complaining about the $(...) part specifically, but about the MACRO part. No matter how you try to prettify it,$(MACRO x y z) is still
MACRO x y z. As long as you have a single syntax for all macros,
the syntax people won't be happy. What they are clamoring for is
dedicated syntax for the most common macros, so that they don't have
to keep repeating the MACRO part of the invocation.

That's a bit of a bummer because that seems a slippery slope to me.
But I guess we could standardize on markdown syntax.

Unfortunately it seems Walter is against it.

One at a time :)

But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
but the fact that doc comments can *only* be processed by ddoc. If there
was a way to get the raw text out, the people who dislike ddoc can pipe
it to the formatter of their own choice, and they would be happy. People
who are indifferent will get ddoc by default, which, despite its flaws,
isn't really *that* horrible.

That's pretty much the very charter of ddoc- most misunderstood tool ever.
Luckily I'll send some pull requests that simplify generation - some time
next year :o)

Dec 31 2014
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:
But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
but the fact that doc comments can *only* be processed by ddoc. If there
was a way to get the raw text out, the people who dislike ddoc can pipe
it to the formatter of their own choice, and they would be happy. People
who are indifferent will get ddoc by default, which, despite its flaws,
isn't really *that* horrible.

That's pretty much the very charter of ddoc- most misunderstood tool ever.
Luckily I'll send some pull requests that simplify generation - some time
next year :o)

My problem is very much the opposite: it's not that only ddoc can process ddoc
syntax, it's that raw ddoc syntax is, often, not very human-readable.  For me
it's very important that the documentation should be trivially comprehensible
_when browsing source code_, and too often Ddoc markup prevents that.

Jan 01 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:10 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:
But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
but the fact that doc comments can *only* be processed by ddoc. If there
was a way to get the raw text out, the people who dislike ddoc can pipe
it to the formatter of their own choice, and they would be happy. People
who are indifferent will get ddoc by default, which, despite its flaws,
isn't really *that* horrible.

That's pretty much the very charter of ddoc- most misunderstood tool
ever.
Luckily I'll send some pull requests that simplify generation - some time
next year :o)

My problem is very much the opposite: it's not that only ddoc can
process ddoc syntax, it's that raw ddoc syntax is, often, not very
human-readable.  For me it's very important that the documentation
should be trivially comprehensible _when browsing source code_, and too
often Ddoc markup prevents that.

Got it. I think auto-macroizing would help with that. -- Andrei

Jan 01 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton
Wakeling via Digitalmars-d wrote:
My problem is very much the opposite: it's not that only ddoc
can process ddoc syntax, it's that raw ddoc syntax is, often,
not very human-readable.

Yeah. The enormous irony is the #1 ddoc justification - and one
of the big reasons doxygen or xml wasn't used IIRC - is

1. It looks good as embedded documentation, not just after it is
extracted and processed.

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

http://dlang.org/ddoc.html

blargh :(

Jan 01 2015
"ponce" <contact gam3sfrommars.fr> writes:
On Thursday, 1 January 2015 at 14:16:05 UTC, Adam D. Ruppe wrote:
On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton
Wakeling via Digitalmars-d wrote:
My problem is very much the opposite: it's not that only ddoc
can process ddoc syntax, it's that raw ddoc syntax is, often,
not very human-readable.

Yeah. The enormous irony is the #1 ddoc justification - and one
of the big reasons doxygen or xml wasn't used IIRC - is

1. It looks good as embedded documentation, not just after it
is extracted and processed.

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

http://dlang.org/ddoc.html

blargh :(

I actually like DDoc as it is, and finds it readable.
Markdown is readable and all but the specifications are just
insane.
http://commonmark.org/

Jan 01 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote:
I actually like DDoc as it is, and finds it readable.

You know, if $(D_CODE) escaped the code properly and code was a shortcut to it... that'd actually solve my big complaints with the ddoc language itself and make it convenient. Really, those are the two things I want, I don't really care about the rest of the argument. Maybe it is PR time.  Jan 01 2015 "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes: On Thursday, 1 January 2015 at 14:37:31 UTC, Adam D. Ruppe wrote: On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote: I actually like DDoc as it is, and finds it readable. You know, if$(D_CODE) escaped the code properly and code was
a shortcut to it... that'd actually solve my big complaints
with the ddoc language itself and make it convenient.

For a preview how this might look like:

perl -p -e 's/\$$$D ([^\()]*+(\((?:[^\()]*+|(?1))*$$)*[^\$()]*)\)/$1/g' std/algorithm.d | less  Jan 01 2015 "Dicebot" <public dicebot.lv> writes: On Wednesday, 31 December 2014 at 19:50:49 UTC, Andrei Alexandrescu wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO arg1, arg2) one can write MACRO arg1, arg2.

Andrei

My biggest issue with DDOC compared to popular stuff like
Markdown / ReStructured Text : it doesn't look nice as a source.
Markdown is so cute because it mimics the style of ASCII-based
text file formatting. DDOC is naturally very verbose because of
all $(MACRO stuff) and lack of basic primitives for most common needs. I don't feel like any small change in DDOC will make me like/use it.  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 12/31/14 1:12 PM, Dicebot wrote: I don't feel like any small change in DDOC will make me like/use it. I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: hello world -->$(BACKQUOTED hello world)
"hello world" --> $(QUOTED hello world) 'hello world' -->$(SQUOTED hello world)
_hello world_ --> $(UNDERLINED hello world) *hello world* -->$(STARRED hello world)

... and such. Then generating nice formatting for each of these
constructs is achieved by simply defining these macros appropriately.

Andrei

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:
On 12/31/14 1:12 PM, Dicebot wrote:
I don't feel like any small change in DDOC will make me like/use it.

I'm envisioning quite an interesting possibility in which certain constructs
are
automatically converted to macros:

hello world --> $(BACKQUOTED hello world) "hello world" -->$(QUOTED hello world)
'hello world' --> $(SQUOTED hello world) _hello world_ -->$(UNDERLINED hello world)
*hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately. " and  naturally come in pairs, but *, _ and ' do not.  Jan 01 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 1:39 AM, Walter Bright wrote: On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote: On 12/31/14 1:12 PM, Dicebot wrote: I don't feel like any small change in DDOC will make me like/use it. I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: hello world -->$(BACKQUOTED hello world)
"hello world" --> $(QUOTED hello world) 'hello world' -->$(SQUOTED hello world)
_hello world_ --> $(UNDERLINED hello world) *hello world* -->$(STARRED hello world)

... and such. Then generating nice formatting for each of these
constructs is
achieved by simply defining these macros appropriately.

" and  naturally come in pairs, but *, _ and ' do not.

Stars and underlines are popular due to markdown. There'd be
limitations, e.g. pairs occurring across a ddoc parent won't be
considered for expansion etc. Also the defaults can be written to be
idempotent. (Below I am removing the single quote because indeed it's
not fitting):

BACKQUOTED=$0 QUOTED="$0"
UNDERLINED=_$0_ STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out
under what circumstances the macros expand. I think we can get this working.

Andrei

Jan 01 2015
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 01:47:27 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

Stars and underlines are popular due to markdown.

we were using that long before markdown was invented. FIDOnet,
newsgroups with UUCP, you name it.

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:
Stars and underlines are popular due to markdown. There'd be limitations, e.g.
pairs occurring across a ddoc parent won't be considered for expansion etc.
Also
the defaults can be written to be idempotent. (Below I am removing the single
quote because indeed it's not fitting):

BACKQUOTED=$0 QUOTED="$0"
UNDERLINED=_$0_ STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out under
what circumstances the macros expand. I think we can get this working.

Ddoc assumes ( ) nests. But this would require that these characters nest, too:

*abc_def * _i

for example, which is stretching things a bit because they do not naturally
nest.

Jan 01 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 11:33:25 UTC, Walter Bright wrote:
Ddoc assumes ( ) nests. But this would require that these
characters nest, too:

*abc_def * _i

for example, which is stretching things a bit because they do
not naturally nest.

I think someone who writes *long bold text

like this*

is in error anyway; I lose track of what those stars are supposed
to me. (BTW the gmail html to text converter does this, making
emails unreadable to me!)

I would say the pattern to match would be \w\*[a-zA-Z0-9]+\*\w.

Honestly, I think _foo_ and /foo/ are both not worth supporting
in this context. *bold* is the only one we really need - the most
common, and the least ambiguous.

We do NOT want it to think *a = *b; is supposed to be bolding. We
do NOT want it to think _object._method is supposed to be
underlined. We do NOT want it to think /bin/bash is supposed to
be italic. (Granted, those might be in code blocks anyway, but
still, no point making this harder than it has to be.)

But when would you write *a* = foo in code? Never, I don't think
that's ever valid. So making that a $(STARRED) macro should just work in pretty much all circumstances. And we can always fall back on$(B bold) and $(I italic) when we do need them. I just think shooting for an 80% solution is more reasonable than a 99 or 100% solution - just do the easiest, least ambiguous shortcuts and use macros for the rest of them. It'll probably go a LONG way. Again those are: *bold* and code.  Jan 01 2015 Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes: On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote: Again those are: *bold* and code. I would be inclined to prefer code or code, simply because it's valid D syntax to have, auto someString = Some great big string;  Jan 01 2015 "Adam D. Ruppe" <destructionator gmail.com> writes: On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: I would be inclined to prefer code or code, simply because it's valid D syntax to have, auto someString = Some great big string; Eh, that breaks my habit from stack overflow. How often do you write an inline raw string anyway? It'd still just work inside ---\ncode\n--- blocks, and you could still do$(D_CODE auto s =
code;) if you wanted to.

Jan 01 2015
"ponce" <contact gam3sfrommars.fr> writes:
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton
Wakeling via Digitalmars-d wrote:
On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
Again those are: *bold* and code.

I would be inclined to prefer code or code, simply
because it's valid D syntax to have,

auto someString = Some great big string;

Github, Stack Overflow, trac and others use one single escape
quote.

Jan 01 2015
"Dicebot" <public dicebot.lv> writes:
On Thursday, 1 January 2015 at 15:21:40 UTC, ponce wrote:
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton
Wakeling via Digitalmars-d wrote:
On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
Again those are: *bold* and code.

I would be inclined to prefer code or code, simply
because it's valid D syntax to have,

auto someString = Some great big string;

Github, Stack Overflow, trac and others use one single escape
quote.

And such snippet is much more likely to go into dedicated code
block:


auto someString = Some great big string;


than as an inline snippet.

Jan 01 2015
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 15:40:30 +0100
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
Again those are: *bold* and code.

=20
I would be inclined to prefer code or code, simply because it's=

valid=20
D syntax to have,
=20
auto someString =3D Some great big string;
=20

i think that in most cases you can use r"..." instead. and if you
really want backticks, you can use dedicated code block for that.

Jan 01 2015
Jacob Carlborg <doob me.com> writes:
On 2015-01-02 02:31, ketmar via Digitalmars-d wrote:

i think that in most cases you can use r"..." instead. and if you
really want backticks, you can use dedicated code block for that.

One really good use case for backticks is when the string contains
double quotes.

--
/Jacob Carlborg

Jan 02 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 6:26 AM, Adam D. Ruppe wrote:
Honestly, I think _foo_ and /foo/ are both not worth supporting in this
context. *bold* is the only one we really need - the most common, and
the least ambiguous.

Maybe not even *bold*. Good documentation uses bold sparingly, and most
uses of bold in dlang.org should actually be code. -- Andrei

Jan 02 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:06 AM, Andrei Alexandrescu wrote:
Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of
bold in dlang.org should actually be code. -- Andrei

I agree. Excessive use of bold is like shouting at people - it's wearying to
read. Pull any programming book off the shelf and flip through it. There's very
little use of bold.

Jan 02 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote:
I agree. Excessive use of bold is like shouting at people -
it's wearying to read. Pull any programming book off the shelf
and flip through it. There's very little use of bold.

Aye, my opinion now is that code is the only really important
one. I can live without the others.

List, table, and link might be nice, but totally non-essential in
my eyes; plain ASCII or recursive macros look good enough to me.

Jan 02 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:42 PM, Adam D. Ruppe wrote:
On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote:
I agree. Excessive use of bold is like shouting at people - it's wearying to
read. Pull any programming book off the shelf and flip through it. There's
very little use of bold.

Aye, my opinion now is that code is the only really important one. I can live
without the others.

List, table, and link might be nice, but totally non-essential in my eyes;
plain
ASCII or recursive macros look good enough to me.

I agree. I was telling Andrei last night what a good idea you'd had.

Jan 02 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 3:32 AM, Walter Bright wrote:
On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:
Stars and underlines are popular due to markdown. There'd be
limitations, e.g.
pairs occurring across a ddoc parent won't be considered for expansion
etc. Also
the defaults can be written to be idempotent. (Below I am removing the
single
quote because indeed it's not fitting):

BACKQUOTED=$0 QUOTED="$0"
UNDERLINED=_$0_ STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out
under
what circumstances the macros expand. I think we can get this working.

Ddoc assumes ( ) nests. But this would require that these characters
nest, too:

*abc_def * _i

for example, which is stretching things a bit because they do not
naturally nest.

No nesting. Again I'm talking simple rules. They should get us a ton of
mileage. -- Andrei

Jan 01 2015
Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/1/15 4:39 AM, Walter Bright wrote:
On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:
On 12/31/14 1:12 PM, Dicebot wrote:
I don't feel like any small change in DDOC will make me like/use it.

I'm envisioning quite an interesting possibility in which certain
constructs are
automatically converted to macros:

hello world --> $(BACKQUOTED hello world) "hello world" -->$(QUOTED hello world)
'hello world' --> $(SQUOTED hello world) _hello world_ -->$(UNDERLINED hello world)
*hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately. " and  naturally come in pairs, but *, _ and ' do not. What about #[{( anything inside here can use markdown )}]# I'm half joking about the brackets, but some method of saying "in here, I permit markdown" would make this both backwards compatible, and not inflict too much damage to readability of ddoc. In fact, if you did something like: /**[[ ... comments with markdown ]]*/ or something like this at the beginning of each ddoc comment, it would be almost unnoticeable. I'd also suggest giving a toggling mechanism, something like: /**$(MARKDOWN true/false)
**/

Which allows one to set the default for the enclosed ddocs.

That's my contribution to the project :) I wish I could actually code it...

-Steve

Jan 02 2015
"H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 01:19:06AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
On 12/31/14 1:12 PM, Dicebot wrote:
I don't feel like any small change in DDOC will make me like/use it.

I'm envisioning quite an interesting possibility in which certain
constructs are automatically converted to macros:

hello world --> $(BACKQUOTED hello world) "hello world" -->$(QUOTED hello world)
'hello world' --> $(SQUOTED hello world) _hello world_ -->$(UNDERLINED hello world)
*hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately. [...] Nice idea, but I think _..._ will have to be left out, due to the prevalence of special meanings of _ currently in use. For example, _abc currently means "abc" without any automatic highlighting (e.g., if abc were a parameter or function name); _abc: at the beginning of a line means a literal word "abc" where otherwise abc: would mean a section heading "abc"; and abc_def: means a section heading with two words "abc def". I anticipate that overloading _ to do even more than this will only lead to a nasty mess where it's impossible for the non-expert to figure out what it actually means. T -- The early bird gets the worm. Moral: ewww...  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Wed, 31 Dec 2014 11:50:51 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: In wake of the recent discussions on improving ddoc syntax we're looking= =20 at doing something about it. Please discuss any ideas you might have=20 here. Thanks! ahem... kill it and use markdown instead.  Dec 31 2014 "Freddy" <Hexagonalstar64 gmail.com> writes: On Wednesday, 31 December 2014 at 21:51:32 UTC, ketmar via Digitalmars-d wrote: On Wed, 31 Dec 2014 11:50:51 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! ahem... kill it and use markdown instead. http://commonmark.org/  Dec 31 2014 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Wed, 31 Dec 2014 22:58:46 +0000 Freddy via Digitalmars-d <digitalmars-d puremagic.com> wrote: On Wednesday, 31 December 2014 at 21:51:32 UTC, ketmar via=20 Digitalmars-d wrote: On Wed, 31 Dec 2014 11:50:51 -0800 Andrei Alexandrescu via Digitalmars-d=20 <digitalmars-d puremagic.com> wrote: In wake of the recent discussions on improving ddoc syntax=20 we're looking at doing something about it. Please discuss any=20 ideas you might have here. Thanks! ahem... kill it and use markdown instead. =20 http://commonmark.org/ ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise.  Dec 31 2014 Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes: On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise. I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the two compare and whether it's worth considering looking into. I personally agree the ddoc macro's can introduce a lot of visual noise.  Dec 31 2014 "Adam D. Ruppe" <destructionator gmail.com> writes: On Wednesday, 31 December 2014 at 23:14:33 UTC, Andrej Mitrovic via Digitalmars-d wrote: I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org You might be able to do an automatic conversion even... either ddoc macros (LOL) or a html to text converter.  Dec 31 2014 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise. =20 I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the two compare and whether it's worth considering looking into. =20 I personally agree the ddoc macro's can introduce a lot of visual noise. there is no sense in demonstrating anything, as Walter and Andrei seems to be sure that Ddoc is human-readable, and there's no much sense in changing it, as people should always generate html/TeX/other output, not trying to read the documentation right in .d files. anything less powerful than Ddoc will be rejected with arbitrary reason (see Walter posts about escaping in markdown, for example).  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes: ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise. I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the two compare and whether it's worth considering looking into. I personally agree the ddoc macro's can introduce a lot of visual noise. there is no sense in demonstrating anything, as Walter and Andrei seems to be sure that Ddoc is human-readable, and there's no much sense in changing it, as people should always generate html/TeX/other output, not trying to read the documentation right in .d files. anything less powerful than Ddoc will be rejected with arbitrary reason (see Walter posts about escaping in markdown, for example). That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei  Dec 31 2014 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 1 Jan 2015 05:50:18 +0000 (UTC) Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei "After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it."  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 12/31/14 10:00 PM, ketmar via Digitalmars-d wrote: On Thu, 1 Jan 2015 05:50:18 +0000 (UTC) Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei "After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it." Sadly indeed that muffles any point you're trying to make around here. Time for a New Year Resolution? :o) -- Andrei  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 1 Jan 2015 05:50:18 +0000 (UTC) Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> wrote: =20 On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote: ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise. =20 I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the t= wo compare and whether it's worth considering looking into. =20 I personally agree the ddoc macro's can introduce a lot of visual noise. =20 there is no sense in demonstrating anything, as Walter and Andrei seems to be sure that Ddoc is human-readable, and there's no much sense in changing it, as people should always generate html/TeX/other output, not trying to read the documentation right in .d files. anything less powerful than Ddoc will be rejected with arbitrary reason (see Walter posts about escaping in markdown, for example). =20 That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei p.s. i already demonstrated excerpt from std.algorithm in that other topic. Walter says that i didn't bother to format Ddoc noise, not even reading my post about it till the end, where i told that there is no much sense in formatting Ddoc, as it will still be noise. so i will not even to try to do it again and again just to read the same answers again and again. about "that needs escaping too", about "we can't specify different fonts there" and so on. i wrote several times that Ddoc is reminding DTP, and it is not human-readable. i even shown the sample. seems that Walter is clearly missing the point of human-readable documentation (i think that he just don't care, as from his POV documentation must be preprocessed to standalone files, there's no reason to read it inside .d source; and he wants powerful preprocessor with DTP features). sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa.  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote: sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa. It would be awesome indeed if the civil atmosphere in this forum would be restored. I very much hope in your help with this. -- Andrei  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 01 Jan 2015 01:30:58 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote: sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa. =20 It would be awesome indeed if the civil atmosphere in this forum would=20 be restored. I very much hope in your help with this. -- Andrei i'm trying to do my best. honestly! ;-) i'm deleting first two or three variants of many replies. so my answers looks perfectly calm for me... until i see them posted. yet i'll try to improve than situation in this year. maybe deleting first ten variants, i don't know... ;-)  Jan 01 2015 Steven Schveighoffer <schveiguy yahoo.com> writes: On 1/1/15 4:46 AM, ketmar via Digitalmars-d wrote: On Thu, 01 Jan 2015 01:30:58 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote: sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa. It would be awesome indeed if the civil atmosphere in this forum would be restored. I very much hope in your help with this. -- Andrei i'm trying to do my best. honestly! ;-) i'm deleting first two or three variants of many replies. so my answers looks perfectly calm for me... until i see them posted. yet i'll try to improve than situation in this year. maybe deleting first ten variants, i don't know... ;-) This is a frequent habit of mine, I always re-read my posts until I feel comfortable that I wouldn't mind reading it (most of the time, it takes at least 2 reviews). Anything especially antagonistic usually gets extra scrutiny :) If NNTP posted replies as I typed them, I would be banned for sure... -Steve  Jan 02 2015 Walter Bright <newshound2 digitalmars.com> writes: On 12/31/2014 3:19 PM, ketmar via Digitalmars-d wrote: Walter and Andrei seems to be sure that Ddoc is human-readable, It doesn't help matters when the examples posted to show how "unreadable" Ddoc is are both misuse of Ddoc and extremely poor whitespace formatting, comparing it with carefully formatted Markdown. I've seen this repeatedly in that thread, by multiple authors, including you. It is not compelling any more than if I tried to show D was better than C++ by showing sloppy and incompetently written C++ code. anything less powerful than Ddoc will be rejected with arbitrary reason (see Walter posts about escaping in markdown, for example). The complaint was made about needing escaping in Ddoc, and then it is arbitrary when I point out that all markup languages need escaping, including Markdown? And lastly, the general problem users have with documentation in Phobos is not that it is written in Ddoc. That has NOTHING to do with it, it's an excuse. Nobody has yet taken me up on my offer to take their text documentation and add markup for them. Few people being willing to write good content is the problem. No documentation tool can fix that. Non-existent documentation can be not written using any tool. Some have been recently stepping up to create PRs to fix documentation in Phobos. That's what we need, and I thank the people doing it: aldacron, AndrejMitrovic, JakobOvrum, quickfur, ntrel, andralex, klickverbot, kiith-sa, Dicebot, schveiguy to name some.  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 01 Jan 2015 01:07:37 -0800 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote: And lastly, the general problem users have with documentation in Phobos i= s not=20 that it is written in Ddoc. That has NOTHING to do with it, it's an excus= e.=20 Nobody has yet taken me up on my offer to take their text documentation a= nd add=20 markup for them. Few people being willing to write good content is the pr= oblem.=20 No documentation tool can fix that. Non-existent documentation can be not= =20 written using any tool. Adam already told that people who can write good documentation is rarely need it. so they just DON'T HAVE that documentation written in the way it can be useful for others. so the only way to make such people write something is to make documentation formatting unintrusive. Ddoc IS intrusive. i can fix something if i can read it, and i can't read that Ddoc mess. so i'm going to dlang.org to look at the dox instead of looking it right in the Phobos sources. and if i see something that can/should be fixed on dlang.org... ah, well, i have to drop the thing i was doing, open another terminal, go to Phobos source directory, find the file with the dox, then find the place to fix... screw it, i was looking at documentation for doing completely different things! but see, if Phobos documentation is human-readable without preprocessing, it's WAY EASIER for me to just open Phobos source file and look there. and guess what i'll do if i'll see that something needs fixing there? yep, i'll fix that, 'cause i'm already at the place that needs fixing. the process is not distractive. and then i can do 'git diff' and send a patch. the whole point is that Ddoc is *not* *human* *readable*. so why i should look to Phobos sources and try to decipher it? and i don't want to drop whatever i was doing to go from the site to Phobos. and when i done with my task, i already forgot what requires fixing (or exhausted and don't want to do it). i understand that D is your child, and you are working on it with passion. but for me D is the tool to solve my tasks. i'm ready to help improving that tool, but only if that's as easy as possible for me. when i done with my task, i already know what i wanted to know, so there is little sense in fixing that. i'm done with it, now i remember it. or at least remember in which of my source files i should look when i need to refresh my memory (yep, i'm looking for usage samples and patterns in my sources if i can, 'cause it's way easier to open another source file for me than to go to some webpage, even local one). that's why i'm advocating human-readable markup. it's easier to read. it's easier to write. it's easier to fix. it can be used without preprocessor. any decent IDE (and even my patched mcedit) can open source file with function definition in one or two clicks. i can't fix it inplace -- i will not fix it. i can't do 'git diff' with it -- i will not fix it. i can't read it -- i will not fix it. and all this is solvable, even without sacrificing your beloved Ddoc: we can have BOTH markdown-like and Ddoc simultaneously. do that and see what language people will prefer to use.  Jan 01 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote: i can fix something if i can read it, and i can't read that Ddoc mess. so i'm going to dlang.org to look at the dox instead of looking it right in the Phobos sources. and if i see something that can/should be fixed on dlang.org... ah, well, i have to drop the thing i was doing, open another terminal, go to Phobos source directory, find the file with the dox, then find the place to fix... screw it, i was looking at documentation for doing completely different things! but see, if Phobos documentation is human-readable without preprocessing, it's WAY EASIER for me to just open Phobos source file and look there. and guess what i'll do if i'll see that something needs fixing there? yep, i'll fix that, 'cause i'm already at the place that needs fixing. the process is not distractive. and then i can do 'git diff' and send a patch. All you need is a mail client seeing as Walter offered you twice to email him any fixes you have and he'll integrate them for you. (Not to mention you refuse to use github etc.) Honestly if someone would pass similarly constructed arguments by you, would you put any weight on their opinion? I find your posts oddly awesome. Such cognitive dissonance is the stuff of legends. -- Andrei  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 01 Jan 2015 01:43:13 -0800 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote: i can fix something if i can read it, and i can't read that Ddoc mess. so i'm going to dlang.org to look at the dox instead of looking it right in the Phobos sources. and if i see something that can/should be fixed on dlang.org... ah, well, i have to drop the thing i was doing, open another terminal, go to Phobos source directory, find the file with the dox, then find the place to fix... screw it, i was looking at documentation for doing completely different things! but see, if Phobos documentation is human-readable without preprocessing, it's WAY EASIER for me to just open Phobos source file and look there. and guess what i'll do if i'll see that something needs fixing there? yep, i'll fix that, 'cause i'm already at the place that needs fixing. the process is not distractive. and then i can do 'git diff' and send a patch. =20 All you need is a mail client seeing as Walter offered you twice to=20 email him any fixes you have and he'll integrate them for you. (Not to=20 mention you refuse to use github etc.) Honestly if someone would pass=20 similarly constructed arguments by you, would you put any weight on=20 their opinion? I find your posts oddly awesome. Such cognitive=20 dissonance is the stuff of legends. -- Andrei you seem to miss my point completely. i'm *not* doing any fixes at all. if Phobos documentation will be human-readable, i will not go to dlang.org ever, i will use Phobos sources instead. i.e. i will look for documentation right in the Phobos sources, not on some website. and surely, it's easy to fix something if the file where it must be fixed is already open in your editor, and exatly on the place which needs fixing. but going from website all way down to Phobos src, and then struggling with Ddoc... no, thanks. i'm not reading that dox for fun and enjoyment. if i'm reading dox it means that i got some problem that i need to solve, and distracting me for too long from that problem is destructive for my workflow. fixing something that is already before my eyes and ready to be edited is ok. dropping my work to fix something that is both far away and requires to grasp non-readable formatting is no-no. having human-readable formatting for documentation solves that problem. it's still possible to generate standalone dox with it, but it's now possible to read dox without generating anything, just in place where that dox was created. and most existing dox can be magically converted to human-readable format too.  Jan 01 2015 Rikki Cattermole <alphaglosined gmail.com> writes: On 1/01/2015 8:50 a.m., Andrei Alexandrescu wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO arg1,
arg2) one can write MACRO arg1, arg2.

Andrei

1. We need to control whitespace
This includes indentation of output elements and new lines added
Use case:
JSON, YAML
2. Allow usage of CTFE as a macro.
Seriously, let actual D code act as a macro.
Also a trait to use a macro. Maybe even extend allMembers for it too.
Use case:
Any advanced macros such as find and replace.
3. It should be possible to not use DDOC macros inside e.g. function
comment to make it readable when exported.
I'm not sure how this would work, but most likely some form of catch
all would be needed.
Use case:
Markdown as format but still outputs clean and nice text.
But also outputting e.g. JSON with clean structure.

Dec 31 2014
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 12:49:06 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

2. Allow usage of CTFE as a macro.

this what Ddoc is really should be. no need in anything other: let all
documentation be processed by CTFE. not by per-function basis though:
compiler must collect *all* documentation and then call one CTFE entry
point to process it. if we gave multiple source files in the command
line, it should collect documentation from all that source files. this
is to allow keeping some state when processing docs.

and then everything Ddoc macros does now can be written in D. and if
someone wants markdown... he will just write a markdown processor in D,
and BLAM! there is markdown processor, without patching the compiler.

ah, and compiler source can be made simplier, as Ddoc can be removed
altogether.

it's perfect. it will solve ALL problems. it will allow people to use
anything they like. and we already has the D interpreter to power it.

Dec 31 2014
Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 12:59 p.m., ketmar via Digitalmars-d wrote:
On Thu, 01 Jan 2015 12:49:06 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

2. Allow usage of CTFE as a macro.

this what Ddoc is really should be. no need in anything other: let all
documentation be processed by CTFE. not by per-function basis though:
compiler must collect *all* documentation and then call one CTFE entry
point to process it. if we gave multiple source files in the command
line, it should collect documentation from all that source files. this
is to allow keeping some state when processing docs.

and then everything Ddoc macros does now can be written in D. and if
someone wants markdown... he will just write a markdown processor in D,
and BLAM! there is markdown processor, without patching the compiler.

ah, and compiler source can be made simplier, as Ddoc can be removed
altogether.

it's perfect. it will solve ALL problems. it will allow people to use
anything they like. and we already has the D interpreter to power it.

Following this, we could extend this one altogether.
AST entry points. Read only (later maybe not) full access to dmd-fe AST.

e.g.

__ast(__ASTTree tree) {
string output = "<modules>";
foreach(string name, __ASTModule theModule; tree.modules) {
string theOutput;
output ~= "<module name=\"" ~ name ~ "\">";
output ~= "<doc>";
output ~= preprocessor(theModule.comment);
output ~= "</doc>";
output ~= "</module>";

output ~= theOutput;
// __DDOC ~= theOutput;
}
__DDOC/*[0]*/ = output ~ "</modules>";
}

Multiple __ast functions is not invalid. But one per module.
One caveat of this however is that if you have these modules they would
be required to be almost 100% standalone.
Example usage with dub, is you have an independent package that supplies
a YAML output with markdown format. To do so you will want you package
as well as possibly all predecessor and successor packages to use that
format. To do so, dub could rebuild all dependencies and pass in those
extra files. And any successor packages will have it added as a
dependency and not -I'd.

This could really kill so many birds. We could even get rid of traits
and prefer __ast(Type/Symbol) to get the AST for it.
And remember how we don't know about all modules? That's the thing, with
this approach its designed to not assume it has all. But it can see them
at some point thanks to e.g. dub.

Although this is a little extreme compared to my original post...

Dec 31 2014
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 13:21:16 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

Although this is a little extreme compared to my original post...

a little. ;-)

yes, processing ASTs with CTFE will be great, but this is huge task.
replacing Ddoc with CTFE which receives an array (tuple? ;-) of
functions with documentation text (preprocessed a little, see below) is
a lighter task. then we can use compile-time introspection to get
function args and so, and format the output as we like.

"small preprocessing" converts the following:

/** text0
* text1
* text2
*/

to:

text0
text1
text2

i.e. just removing that indentation with corresponding '*'. it's easy
and must be done for any formatting, so it can be done before invoking
CTFE. just make sure that the following will not be processed:

/** text0
* text1
heh
* text2
*/

there is no vertical line of '*', so no need to remove leading '*' here.

Dec 31 2014
Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 1:35 p.m., ketmar via Digitalmars-d wrote:
On Thu, 01 Jan 2015 13:21:16 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

Although this is a little extreme compared to my original post...

a little. ;-)

yes, processing ASTs with CTFE will be great, but this is huge task.
replacing Ddoc with CTFE which receives an array (tuple? ;-) of
functions with documentation text (preprocessed a little, see below) is
a lighter task. then we can use compile-time introspection to get
function args and so, and format the output as we like.

"small preprocessing" converts the following:

/** text0
* text1
* text2
*/

to:

text0
text1
text2

i.e. just removing that indentation with corresponding '*'. it's easy
and must be done for any formatting, so it can be done before invoking
CTFE. just make sure that the following will not be processed:

/** text0
* text1
heh
* text2
*/

there is no vertical line of '*', so no need to remove leading '*' here.

I was thinking one simpler.
$(D myfunction,$0)

This will be enough of a big task, but enough of a pay off to make it
worth while.
The AST stuff would guaranteed be a DIP (second to last CTFE
implementation type, well as I define it anyway).

Dec 31 2014
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 13:44:23 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

I was thinking one simpler.
$(D myfunction,$0)

it's not really better than current Ddoc. sure, you can use it to write
custom doc processor, but you can't store state with it, and you still
have to escape alot. this actually making Ddoc *worse*, as it adds
complexity.

Dec 31 2014
Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 1:54 p.m., ketmar via Digitalmars-d wrote:
On Thu, 01 Jan 2015 13:44:23 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

I was thinking one simpler.
$(D myfunction,$0)

it's not really better than current Ddoc. sure, you can use it to write
custom doc processor, but you can't store state with it, and you still
have to escape alot. this actually making Ddoc *worse*, as it adds
complexity.

At the very least, atleast the compiler wouldn't need changes per each
different doc processor.
I can understand state being an issue. But this atleast will use CTFE to
extend DDOC just enough to make it more useful.

For full AST access which basically has state local to the function, its
too much code on the compiler side to make it worth while right now. But
this is a nice compromise IMO.

Dec 31 2014
Jacob Carlborg <doob me.com> writes:
On 2015-01-01 01:44, Rikki Cattermole wrote:

The AST stuff would guaranteed be a DIP (second to last CTFE
implementation type, well as I define it anyway).

http://wiki.dlang.org/DIP50 ;)

--
/Jacob Carlborg

Jan 01 2015
Jacob Carlborg <doob me.com> writes:
On 2015-01-01 01:21, Rikki Cattermole wrote:

Following this, we could extend this one altogether.
AST entry points. Read only (later maybe not) full access to dmd-fe AST.

So we're back at AST macros :). I don't mind but I don't think it's the
right solution in this case.

--
/Jacob Carlborg

Jan 01 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
I'd actually prefer to focus more on ddoc's unique strengths -
that it understands the compiler's scoping rules.

My #1 ddoc wish is not change to macro syntax (i prefer plain
text anyway)... my #1 wish is for all D symbols to be made
available to the output somehow, with their fully-qualified names
and or mangles.

Imagine how cool it would be if you could write

import std.stdio;
/**
---
import std.path;
File f = open(path.whatever());
---
*/
File open(string name);

And have it come out as:

/**
---
$(D_CODE_KEYWORD import) ($D_CODE_IDENT std.path, std.path);
$(D_CODE_IDENT std.stdio.File, File) f = open(path.whatever()); --- */$(D_CODE_IDENT std.stdio.File, File) open(string name);

and so on and so forth.

then we could implement a macro or a "I feel lucky" style search
that links all those D_CODE_IDENT to the right places,
automatically.

I think that'd be pretty boss.

Dec 31 2014
"Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 00:44:33 UTC, Adam D. Ruppe wrote:
I'd actually prefer to focus more on ddoc's unique strengths -
that it understands the compiler's scoping rules.

If I understand this correctly, it seems very compelling to me.
Would it be an option to

1. Work on ddoc (as it is now) to be even closer to the compiler
(e.g. scoping rules)
2. Add a carefully selected markdown on top of proper ddoc (e.g.
use ddoc instead of html as fallback)
3. Provide ddoc macro definitions to generate all kinds of output

This would help in several ways

1. The fully functional ddoc system that can do books remains
available. There is use for it.
2. The code documentation could be much more lightweight (but
still have the full ddoc macros available if needed)
3. Generating to pandoc or the like. There are converters out
there.

If any of this is of any value, I am happy to help to make it
happen.

Jan 01 2015
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
Hello,

In wake of the recent discussions on improving ddoc syntax we're looking at
doing something about it. Please discuss any ideas you might have here.
Thanks!

One simple starter would be to allow one escape character, e.g. the backtick
(), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write MACRO arg1, arg2. I don't really have any particular opinions on this topic, but the only feeling I've really had in the past is, "why is it so different from doxygen?" Most people are already familiar with doxygen. Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start?  Dec 31 2014 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote: On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com> wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO arg1, arg2) one
can write MACRO arg1, arg2.

I don't really have any particular opinions on this topic, but the
only feeling I've really had in the past is, "why is it so different
from doxygen?"
Most people are already familiar with doxygen.

Why is doxygen insufficient? Is there a reason ddoc was invented
rather than supporting the practically-industry-standard doxygen
format from the start?

No particular system was clearly dominant when Walter invented ddoc.
Also I might be frequenting the wrong circles; most people I know and
myself aren't fluent at all with doxygen. -- Andrei

Jan 01 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
No particular system was clearly dominant when Walter invented ddoc. Also I
might be frequenting the wrong circles; most people I know and myself aren't
fluent at all with doxygen. -- Andrei

It is really trivial to learn and quite effective.  I used it years ago for a
C/C++ project; when I encountered Ddoc my reaction was, "OK, it's basically a
custom and slightly weirder-looking variant of Doxygen..."

It has some _very_ nice features such as the easy inclusion of LaTeX formulas
into documentation, and in my experience Doxygen markup is much more
readable-in-source than Ddoc.

Three things I'm not sure about: (i) does it allow definitions of custom macros
as with Ddoc (although I'm not sure how necessary that is in practice); (ii) I
have a nasty feeling its  keyword markup syntax (e.g.  return  param etc.)
might
not play nice with D code examples; (iii) I suspect we'd have to do some
integration work getting D support into Doxygen in order to enjoy the best of
all its features.

Jan 01 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
No particular system was clearly dominant when Walter invented ddoc.
Also I
might be frequenting the wrong circles; most people I know and myself
aren't
fluent at all with doxygen. -- Andrei

It is really trivial to learn and quite effective.

Totally. I did use it briefly a few years ago and I'm sure I can relearn it.

My point here was to give context for ddoc's history. FWIW switching
dlang and phobos now to doxygen would be a major effort and I'm not sure
we'd be in a better place even after assuming perfect execution.

Andrei

Jan 01 2015
"Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 10:16:01 UTC, Andrei Alexandrescu
wrote:
My point here was to give context for ddoc's history. FWIW
switching dlang and phobos now to doxygen would be a major
effort and I'm not sure we'd be in a better place even after
assuming perfect execution.

I don't think the current documentation of phobos is affecting
(professional) D adoption much, although it can improve a lot.
Adoption is a language/compiler/runtime/tooling issue.

On the other hand, if converting phobos' Ddoc into Doxygen cannot
be automated, then that suggests that there is a fundamental
problem with how Ddoc is used as a markup tool.

Adopting Doxygen would give you some benefits:

- it makes D look less weird

- it makes it easier to use existing formatting/presentation
solutions

- it is more motivating to learn Doxygen than figuring out Ddoc
since you can use it for non-D projects

The Doxygen front page advertises the following:

«it also supports other popular programming languages such as C,
Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and
UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent
D.»

D would look better without the "to some extend" and you might
get the Doxygen community to help out with Doxygen relevant
tooling issues if it is the default D documentation tool.
Basically an opportunity for synergy.

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 3:09 AM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?=
<ola.fosheim.grostad+dlang gmail.com>" wrote:
Adopting Doxygen would give you some benefits:

"Doxygen is developed under Mac OS X and Linux, but is set-up to be highly
portable. As a result, it runs on most other Unix flavors as well. Furthermore,
executables for Windows are available."

-- http://www.stack.nl/~dimitri/doxygen/

There are no packages for FreeBSD, for example.

Doxygen is GPL, but appears to be supported by only one person.

There is also nothing stopping anyone from using Doxygen if they prefer it.

Jan 01 2015
"Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 12:05:03 UTC, Walter Bright wrote:
There is also nothing stopping anyone from using Doxygen if
they prefer it.

Sure, but there is a big advantage in having a the same tech doc
format for all libraries for the same language/group of languages.

I've spent way too much time learning new essential languages, so
learning a new one for a fringe activity like writing tech docs
is not going to happen.

Picking a common subset of an existing markup language will
reduce resistance to learning the one D is using. Doxygen syntax
is a good candidate if you want people to write uniform docs for
D libraries. Especially if D is going to continue to focus on C++
integration.

Jan 01 2015
Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/1/15, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
Totally. I did use it briefly a few years ago and I'm sure I can relearn
it.

The wxWidgets developers maintain a hand-written set of doxygen
interface files because doxygen actually crashes when trying to parse
the C++ code directly.

As a result the documentation is frequently out of date. I remember
filing numerous patches to fix their docs (over 100 of them), it was
blatantly out of date[1].

We would have the same problem with D. Any time there were syntax
changes in D we would have to fix doxygen to be able to parse D code
again.

Anyway, maybe we can do something about ddoc and make it easier to
use. I'm just saying the grass isn't necessarily greener on the other
side.

[1]: http://trac.wxwidgets.org/search?ticket=on&q=drey&page=13&noquickjump=1

Jan 01 2015
"Piotrek" <none nowhere.pl> writes:
On Thursday, 1 January 2015 at 13:28:39 UTC, Andrej Mitrovic via
Digitalmars-d wrote:
Anyway, maybe we can do something about ddoc and make it easier
to use. I'm just saying the grass isn't necessarily greener
on the other side.

+1. Every documentation tool has its problems. IMO, changing
documentation system from the dedicated one would be a step
backwards.

Piotrek

Jan 01 2015
Jacob Carlborg <doob me.com> writes:
On 2015-01-01 14:28, Andrej Mitrovic via Digitalmars-d wrote:

The wxWidgets developers maintain a hand-written set of doxygen
interface files because doxygen actually crashes when trying to parse
the C++ code directly.

As a result the documentation is frequently out of date. I remember
filing numerous patches to fix their docs (over 100 of them), it was
blatantly out of date[1].

We would have the same problem with D. Any time there were syntax
changes in D we would have to fix doxygen to be able to parse D code
again.

I'm pretty sure I read on the Clang mailing list that someone wants to
use Clang to extract doxygen comments.

--
/Jacob Carlborg

Jan 01 2015
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 20:16, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
No particular system was clearly dominant when Walter invented ddoc.
Also I
might be frequenting the wrong circles; most people I know and myself
aren't
fluent at all with doxygen. -- Andrei

It is really trivial to learn and quite effective.

Totally. I did use it briefly a few years ago and I'm sure I can relearn it.

My point here was to give context for ddoc's history. FWIW switching dlang
and phobos now to doxygen would be a major effort and I'm not sure we'd be
in a better place even after assuming perfect execution.

I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

And others are saying "Markdown is the standard."

BTW, Boost doesn't seem to use Doxygen, apparently because it crashes reading
Boost C++ files:

http://stackoverflow.com/questions/3349783/boost-doxygen-documentation

Jan 01 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 20:42, Walter Bright via Digitalmars-d wrote:
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

And others are saying "Markdown is the standard."

I think the two are not in contradiction, because as Manu noted earlier in the
thread, Doxygen now permits Markdown to be used in its documentation.

Jan 01 2015
Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/1/15, Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

And others are saying "Markdown is the standard."

Well the actual truth is that doxygen is pretty much the C++ standard,
while Markdown is a standard for everything else. :)

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 12:02 PM, Andrej Mitrovic via Digitalmars-d wrote:
Well the actual truth is that doxygen is pretty much the C++ standard,
while Markdown is a standard for everything else. :)

My experience with C/C++ is that no documentation is the standard :-)

Jan 01 2015
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 2 January 2015 at 05:42, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

And others are saying "Markdown is the standard."

It is, doxygen supports markdown. Doxygen users are generally familiar
with markdown in docs.

BTW, Boost doesn't seem to use Doxygen, apparently because it crashes
reading Boost C++ files:

http://stackoverflow.com/questions/3349783/boost-doxygen-documentation

Hah. C++ is such a pig, I'm amazed it's actually POSSIBLE to parse it
anymore! ;)

Jan 01 2015
=?UTF-8?Q?Tobias=20M=C3=BCller?= <troplin bluewin.ch> writes:
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com>
wrote:
Three things I'm not sure about: (i) does it allow definitions of custom
macros as with Ddoc (although I'm not sure how necessary that is in
practice); (ii) I have a nasty feeling its  keyword markup syntax (e.g.
return  param etc.) might not play nice with D code examples; (iii) I
suspect we'd have to do some integration work getting D support into
Doxygen in order to enjoy the best of all its features.

AFAIK  keyword is javadoc style (but supported by doxygen) and original
doxygen style uses \keyword.

Jan 02 2015
Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 19:33, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote:
On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d

<digitalmars-d puremagic.com> wrote:
Hello,

In wake of the recent discussions on improving ddoc syntax we're looking
at
doing something about it. Please discuss any ideas you might have here.
Thanks!

One simple starter would be to allow one escape character, e.g. the
backtick
(), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write MACRO arg1, arg2. I don't really have any particular opinions on this topic, but the only feeling I've really had in the past is, "why is it so different from doxygen?" Most people are already familiar with doxygen. Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start? No particular system was clearly dominant when Walter invented ddoc. Okay. Also I might be frequenting the wrong circles; most people I know and myself aren't fluent at all with doxygen. -- Andrei What do you tend to use instead? I miss doxygen's '\' tags. For instance, '\a argName' to refer to a function argument argName, which will be formatted appropriately and all that. I find it a lot less visually distracting. It might also be interesting to note that doxygen implemented markdown support quite some time back, so I think there's precedent for people expecting that markdown be available for use in their documentation.  Jan 01 2015 Manu via Digitalmars-d <digitalmars-d puremagic.com> writes: On 1 January 2015 at 20:02, Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote: No particular system was clearly dominant when Walter invented ddoc. Also I might be frequenting the wrong circles; most people I know and myself aren't fluent at all with doxygen. -- Andrei It is really trivial to learn and quite effective. I used it years ago for a C/C++ project; when I encountered Ddoc my reaction was, "OK, it's basically a custom and slightly weirder-looking variant of Doxygen..." It has some _very_ nice features such as the easy inclusion of LaTeX formulas into documentation, and in my experience Doxygen markup is much more readable-in-source than Ddoc. Three things I'm not sure about: (i) does it allow definitions of custom macros as with Ddoc (although I'm not sure how necessary that is in practice); (ii) I have a nasty feeling its keyword markup syntax (e.g. return param etc.) might not play nice with D code examples; (iii) I suspect we'd have to do some integration work getting D support into Doxygen in order to enjoy the best of all its features. Doxygen supports both param and \param. It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though.  Jan 01 2015 Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes: On 01/01/15 17:16, Manu via Digitalmars-d wrote: Doxygen supports both param and \param. Ah yes, I'd forgotten that. It's been a while :-\ It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though. Did you ever try preserving the docs and continuing to use doxygen to generate them? If so, how did it go? Or is that an outright impossibility?  Jan 01 2015 Manu via Digitalmars-d <digitalmars-d puremagic.com> writes: On 2 January 2015 at 03:06, Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 01/01/15 17:16, Manu via Digitalmars-d wrote: Doxygen supports both param and \param. Ah yes, I'd forgotten that. It's been a while :-\ It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though. Did you ever try preserving the docs and continuing to use doxygen to generate them? If so, how did it go? Or is that an outright impossibility? Doxygen doesn't know about most D-specific concepts stuff. Other language concepts are usually a subset of C/C++, but C++ is really a subset of D. Doxygen needs some new concepts as far as I can tell.  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote: Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start? There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 people used it. The problem was Doxygen was some add on tool. It was not part of the downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going to have to: 1. pray a version exists on the platform they have that D is installed on. 2. pray that version was the one the D docs were expecting. 3. buy Doxygen. 4. download and install Doxygen successfully. 5. Doxygen is a large and complex tool - lots of work to understand it. 6. expect the D community to provide tech support with "Doxygen is not working on my D documents." The end result was, essentially nobody used Doxygen. In fact, nobody used any sort of documentation system, and we know what the result looked like - your typical out-of-date, totally wrong, or non-existent normally found with C and C++ projects. Ddoc, being: 1. always there 2. always the correct version 3. Ddoc is trivial to learn and use revolutionized the D documentation. And that's an understatement.  Jan 01 2015 Manu via Digitalmars-d <digitalmars-d puremagic.com> writes: On 1 January 2015 at 21:51, Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote: Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start? There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 people used it. The problem was Doxygen was some add on tool. It was not part of the downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going to have to: 1. pray a version exists on the platform they have that D is installed on. 2. pray that version was the one the D docs were expecting. 3. buy Doxygen. 4. download and install Doxygen successfully. 5. Doxygen is a large and complex tool - lots of work to understand it. 6. expect the D community to provide tech support with "Doxygen is not working on my D documents." The end result was, essentially nobody used Doxygen. In fact, nobody used any sort of documentation system, and we know what the result looked like - your typical out-of-date, totally wrong, or non-existent normally found with C and C++ projects. Ddoc, being: 1. always there 2. always the correct version 3. Ddoc is trivial to learn and use revolutionized the D documentation. And that's an understatement. I'm not arguing that it wasn't an excellent decision to include a doc parser in DMD, but I don't think any of those advantages are attributed to the ddoc syntax specifically so much as just including it in the compiler. I'm sure the ddoc syntax is fine. It's just noisy and hard to read, as I think we've established to be the popular opinion. I'm just suggesting that DMD could also parse some useful subset of doxygen as ddoc shorthand. I don't think parsing doxygen would be particularly difficult. Basically all the suggestions here so far, like the markdown bits are valid doxygen.  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote: It's just noisy and hard to read, as I think we've established to be the popular opinion. I'm sure we can also agree that: #include\ <stdio.h\ #include\ <stdlib.h> int main\ (){print\ f("hello\ world\n\ ");retur\ n EXIT_S\ UCCESS;} Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. Consider also this Ddoc code: /**************************** This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***************************/ And lastly, people initially hated the D template syntax: foo!(args) foo!arg but today it elicits nary a ripple - it's liked now. It's simply familiar now.  Jan 01 2015 "Adam D. Ruppe" <destructionator gmail.com> writes: On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library. Why the hell were they written that way in the first place? Beats the crap out of me, but they ARE written that way...  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 1/1/2015 12:04 PM, Adam D. Ruppe wrote: On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library. I know. But have you ever seen badly formatted C code? Do you conclude from that that C code is inherently ugly? Or do you say "hey, fix the formatting!" Why the hell were they written that way in the first place? Beats the crap out of me, but they ARE written that way... Yep, and I've seen a lot of crappily formatted D code, too. That's pretty much died down in the Phobos submissions, because the reviewers won't allow it in. Little comparable attention, however, has been paid to the Ddoc style. I did put to rights one of the posted examples: https://github.com/D-Programming-Language/phobos/pull/2828  Jan 01 2015 "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes: On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote: It's just noisy and hard to read, as I think we've established to be the popular opinion. Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. At this point it might be helpful to point out that Ddoc does its jobs very well. It deserves praise on its merits. For properly documented code, however, it requires more visual noise than desirable. Take std/algorithm.d as an example. In my opinion replacing$(D ...) with ... boosts the file
considerably.

The beauty of markdown is that it requires significantly less
visual noise. It is not clean what markdown actually is, so
voting for it might be nonsensical. On the other hand, I believe
in reading source code and some documentation in phobos is
unreadable to me. This is why I think Ddoc should be improved.

Jan 01 2015
ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 11:57:37 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

Is also hard to read. Yes, I'm being facetious, but take a look at those=

=20
examples posted here about how ugly Ddoc is - they're of that category.

and you know why? 'cause nobody cares to make 'em human readable, as
it's almost impossible with Ddoc. so why someone should waste his time
on that?

on contrary, human-readable markup tend to be formatted to be actually
human-readable.

yet i will not argue anymore, as you seem to ignore the fact that most
people don't want to do DTP in API documentation.

this is very easy to judge: just preapprove markdown-like parser for
documentation (without throwing off Ddoc) and then see what people will
use most of the time. i bet you know the answer.

Jan 01 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote:
One simple starter would be to allow one escape character, e.g. the backtick
(), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write MACRO arg1, arg2. Would that be accompanied by deprecation and removal of the$(MACRO arg1, arg2)
syntax?

I ask because for me, one of the biggest annoyances of Ddoc (in terms of source
readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc accidentally seeing a macro where there is none.  Jan 01 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote: One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO arg1, arg2)
one can
write MACRO arg1, arg2.

Would that be accompanied by deprecation and removal of the $(MACRO arg1, arg2) syntax? No. I ask because for me, one of the biggest annoyances of Ddoc (in terms of source readability of the docs) is having to use$(RPAREN) in order to
avoid Ddoc accidentally seeing a macro where there is none.

cd code/d/phobos
git grep RPAREN | wc -l
28

RPAREN is indeed more frequent in dlang.org:

cd code/d/phobos
git grep RPAREN | wc -l
589

Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The
majority are in changelog.dd; I guess a couple of macros might help there.

Andrei

Jan 01 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 11:21, Andrei Alexandrescu via Digitalmars-d wrote:
cd code/d/phobos
git grep RPAREN | wc -l
28

It's a bugbear for std.random because I find myself writing things like:

/**
$(D uniform01) offers a faster generation of random variates than the equivalent$(D uniform!"[$(RPAREN)"(0.0, 1.0)) and so may be preferred for some applications. Returns: Floating-point random variate of type$(D T) drawn from the uniform
distribution across the half-open interval [0, 1$(RPAREN). */ With respect to my other remarks in this thread, the example above is one of the single most annoying human-unreadable things I encounter: I would really, really like mathematics and inline code examples in the docs to not need "escaping" in this manner, so that it's as easy as possible to compare and contrast docs and code in the source file. I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 1/1/2015 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-( Other than the:$(INTERVAL 0, 1)

macro, you can use:

&rparen;

or the unicode &rbbrk; which looks like a right ) :

[0, 1❳

You can also use:

[0, 1[

which is actually an international standard notation:

http://en.wikipedia.org/wiki/ISO_31-11#Sets

Jan 01 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
I'm hoping that I'm just missing a Ddoc trick here, but I don't think so
:-(

You're not but that's really rare. uniform01 is a rare case of unpaired
paren in code. -- Andrei

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 2:21 AM, Andrei Alexandrescu wrote:
Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The
majority are in changelog.dd; I guess a couple of macros might help there.

There are also things in the language spec documentation like:

$(B$(LPAREN) $(RPAREN)) which are simply unnecessary. Instead:$(B ( ))

Jan 01 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
I ask because for me, one of the biggest annoyances of Ddoc (in terms of source
readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc accidentally seeing a macro where there is none. Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN)

which would be better coded as:

$(INTERVAL x .. y) INTERVAL=[$0$(RPAREN)  Jan 01 2015 Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes: On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote: Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN)

which would be better coded as:

$(INTERVAL x .. y) INTERVAL=[$0$(RPAREN) See, this is my point.$(INTERVAL x .. y) is, to my mind, less clear to read
_in the source_ than [x, y).

If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-)  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 1/1/2015 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: See, this is my point.$(INTERVAL x .. y) is, to my mind, less clear to read
_in the source_ than [x, y).

My point is there's ALWAYS going to be some sort of escaping mechanism, and it
is ALWAYS going to interfere with the look of anyone who wants to use the full
character set on the keyboard, which IS going to happen whenever you write math
text.

If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? You don't have to call it INTERVAL. You can write your own macro to name it whatever works for you. I do it all the time. You can even then change the definition of the macro and, for example, have it styled differently (like use a different font, different font weight, different color, etc.) I find that very handy. A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not realizing that C code can contain custom written functions. Here's one example that was brought up in the discussion: https://github.com/D-Programming-Language/phobos/pull/2828 A custom macro made all the difference. Not only that, it is now easy to switch it from a table to a definition list, or have custom styling for it, all without messing anything else up. This cannot be done with Markdown. You might ask "why would we want custom styling"? Turns out that that example is a nice one for why not use it. I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-) Isn't * a super common math character? and |? and +? All of which are markdown characters. The only time the stray paren issue comes up is in the interval notation.  Jan 01 2015 Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes: On 01/01/15 21:15, Walter Bright via Digitalmars-d wrote: My point is there's ALWAYS going to be some sort of escaping mechanism, and it is ALWAYS going to interfere with the look of anyone who wants to use the full character set on the keyboard, which IS going to happen whenever you write math text. Yes, I accept that. I'm just pointing out what I find problematic with this particular escaping mechanism, given the documentation needs of the code I'm involved with. I do however still think that using$( ) to delineate start and end of macro
blocks is a bad choice given the prevalence of ( ) in code.

Before I reply to the rest of your email, I think I should point out two things:

* I understand that ddoc is a macro system, I understand what that
means and how flexible and powerful it can be (I've used LaTeX for
years, and I have created my own custom ddoc macros).  I'm not
trying to persuade you to give that up.

* I'm not trying to advocate for you to start supporting markdown,
although I do understand why some people are.

* LaTeX maths notation on the other hand ... ;-)
- actually I'm mostly raising this last point to
tease you, but there is a serious side; I'll
explain later in the email.

Anyway, to some details ...

You don't have to call it INTERVAL. You can write your own macro to name it
whatever works for you. I do it all the time. You can even then change the
definition of the macro and, for example, have it styled differently (like use
a
different font, different font weight, different color, etc.) I find that very
handy.

Yes, I understand that I can write different macros to mean different things.
But surely you can understand my point from the previous email, that having 4
different macros to indicate the different types of intervals, is much less
nice
from a reading/writing point of view than just being able to write, in ASCII,
[x, y], (x, y], [x, y) and (x, y).

It's not just maths notation either -- this will trigger the 'Stray )' warning
too:

Example:
--------
auto u = uniform!"[)"(0.0, 1.0);
--------

I think we can achieve that simplicity of reading, not just for these two
examples, but for potentially quite a bit more maths and code, without
sacrificing any of the things you're interested in keeping.

A lot of the complaints about Ddoc clearly stem from people not realizing they
can create their own macros. It's like not realizing that C code can contain
custom written functions.

Here's one example that was brought up in the discussion:

https://github.com/D-Programming-Language/phobos/pull/2828

A custom macro made all the difference. Not only that, it is now easy to switch
it from a table to a definition list, or have custom styling for it, all
without
messing anything else up. This cannot be done with Markdown.

You might ask "why would we want custom styling"? Turns out that that example
is
a nice one for why not use it.

Yes, and nothing I say here should be taken as denying the usefulness or
desirability of being able to do that.

BTW talking of custom macros and custom styling, that file has something I
consider to be a horrendous violation of good styling design in it:

MYREF = <font face='Consolas, "Bitstream Vera Sans Mono", "Andale Mono",
Monaco, "DejaVu Sans Mono", "Lucida Console", monospace'><a
href="#.$1">$1</a>&nbsp;</font>

Math notation uses a ton of special characters, it's one of the reasons why
Unicode was invented. Limiting yourself to non-Markdown ascii is extremely
limiting. Heck, look at this:

https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ

Sure, but even with unicode, there's a limit to how sanely you can represent a
complex formula in plain-text.  Personally, this is the point where I'd rather
be able to use inline LaTeX formulas, because I think most people interested in
complex formulas will be able to understand that.

Please don't dismiss this idea out of hand: I think there are some handy tools
we could use to integrate this very well into our documentation system.  Using
the MathJax javascript makes it pretty easy to embed LaTeX formulas into an
HTML
document:
http://www.mathjax.org/

... and obviously when outputting to LaTeX, it becomes much easier to just hand
on LaTeX formulas as they are.

If we could do something like,

$(MATH F(x) = \int_{0}^{10} f(x) dx ) then it would be very nice. Obviously this won't work notationally quite as-is, but I don't see why it shouldn't be possible to find something similar that is workable. (N.B. this is a definite "Dream Wishlist" item, so please don't see it as the main concern of my email; if it isn't workable, just tell me that and move on to the end of the email, where there is the point I really would like your feedback on.) Isn't * a super common math character? and |? and +? All of which are markdown characters. Well, as I'm not arguing for markdown, this may be a moot point. But I don't recall encountering those issues with markdown, because IIRC most markdown use of those special characters is quite context dependent: i.e. *this produces bold or emphasized text* but x * y * z does not :-) ... so it doesn't complicate maths notation as you might think. (The above works at least with GitHub markdown:-) The only time the stray paren issue comes up is in the interval notation. I get that my example is an edge case that may not be the best motivation for you to change how things work. But here's the other idea I'd like to suggest that might help resolve this. Others have suggested this as a shorthand for$(D_CODE ) or whatever.  I'd
like to suggest that instead this be used as a way to indicate to Ddoc:
"There
are no Ddoc macros inside this bit of text, nor will a macro end."

So, for example, I could rewrite my earlier documentation example as:

/**
$(D uniform01) offers a faster generation of random variates than the equivalent$(D uniform!"[)"(0.0, 1.0)) and so may be
preferred for some applications.

Returns:
Floating-point random variate of type $(D T) drawn from the uniform distribution across the half-open interval [0, 1). */ ... and the "Stray ')'" concerns need not arise, because the ... blocks guarantee that any ')' character they contain is not stray. Does this sound at all feasible?  Jan 01 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using$( ) to delineate start and end of
macro blocks is a bad choice given the prevalence of ( ) in code.

s/think/believe/ seeing as you bring awfully little evidence to back
that up. -- Andrei

Jan 02 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote:
On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it). Grep the Phobos sources, the only stray paren issue in it is the use of [..) in a few places in the documentation. I know it's irritating for you, but it simply is not prevalent.  Jan 02 2015 "John Colvin" <john.loughran.colvin gmail.com> writes: On Friday, 2 January 2015 at 21:03:44 UTC, Walter Bright wrote: On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote: On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using$( ) to delineate start
and end of
macro blocks is a bad choice given the prevalence of ( ) in
code.

s/think/believe/ seeing as you bring awfully little evidence
to back that up. --
Andrei

The thing is, ( ) naturally pair in code, and naturally paired
( ) are not an issue in Ddoc. One never sees [..) in code
(maybe Mathematica supports it).

Not that I know of. [ and ] are for function application/calls in
mathematica and ( ) have their normal order-of-evaluation meaning.

Jan 02 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 22:03, Walter Bright via Digitalmars-d wrote:
The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an
issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it).

Er, I believe I posted an example of just that :-)

I'm entirely open to the possibility of reworking the 'uniform' function so
that
its bounds are indicated in a different way, but it _is_ something that
currently occurs in D code (albeit not frequently).

Grep the Phobos sources, the only stray paren issue in it is the use of [..) in
a few places in the documentation. I know it's irritating for you, but it
simply
is not prevalent.

I can live with you not addressing my irritation :-)  But since we're
discussing
how to improve Ddoc, I thought it best to make sure that my issues with it were
well described and understood.

Jan 02 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton
Wakeling via Digitalmars-d wrote:
Er, I believe I posted an example of just that :-)

error stray paren :) Uh oh, another one!

It actually is kinda a pity to me that it is such a common
character. In my macro expander I wrote for css uses this weird
character: ¤ to start a macro. That way, I could be reasonably
sure it would never show up anywhere else, simplifying the code a
bit.

By mapping it to F7 in my editor, it is easily available despite
not being on the keyboard, and it is even in the 8-bit character
set my old fonts use, so it would show up there too.

Imagine if macros were: ¤“name ‗ argument ‗ arg2”!

But I don't suppose we can ask people to map hotkeys to
conveniently write the docs either :(

Jan 02 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 22:40, Adam D. Ruppe via Digitalmars-d wrote:
On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton Wakeling via
Digitalmars-d wrote:
Er, I believe I posted an example of just that :-)

error stray paren :) Uh oh, another one!

It actually is kinda a pity to me that it is such a common character.

/**
You know the worst thing?  I can't use emoticons
in my ddoc ;-)

This makes me very sad, and I can't even express
my sadness without generating another warning. :-(

Although I can, speaking tongue in cheek, see how some
people might consider that a bonus. :-P
*/

Imagine if macros were: ¤“name ‗ argument ‗ arg2”!

But I don't suppose we can ask people to map hotkeys to conveniently write the
docs either :(

Seriously: how feasible could it be to address the issue by delineating the
start and end of macros by a _pair_ of characters, reducing the chance of
ambiguity?

$(NEW_MACRO this would be the new macro system)$

Jan 02 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:23 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
I can live with you not addressing my irritation :-)  But since we're
discussing
how to improve Ddoc, I thought it best to make sure that my issues with it were
well described and understood.

I like to think I do understand the issue :-) even if I don't agree with many
conclusions.

An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of
a
rather simple piece of code.

Jan 02 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 03/01/15 01:11, Walter Bright via Digitalmars-d wrote:
An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of
a
rather simple piece of code.

Very much so, and your point elsewhere in this thread about how valuable it is
to have a built-in documentation tool is absolutely spot-on.  A story to
illustrate this ...

A few days ago I had a go at building and installing the rust compiler (no, I'm
not jumping ship, I just decided it was about time I started getting some
proper
hands-on understanding of some of the alternative design approaches out
there:-).  This uses pandoc to generate documentation, which in turn evokes
pdflatex, xelatex or lualatex, with the last of these being the preferred
option.

One ./configure && make later, and after quite a bit of compilation, the
compiler itself was built -- at which point, the makefile tried to go on and
build the documentation, and failed, for reasons I still don't understand (it
was the lualatex command that was failing, but the error message was not very
clear in conveying what the actual problem was).

OK, well, the compiler is built, right?  So let's try 'make install' ... oh no,
the first thing it tries to do is to complete the 'make all' target and build
the docs, and of course that fails, so it doesn't install anything. :-\

Now, full credit to the rust community: they were immediately friendly and
helpful in advising me how to deal with this (you can pass a flag to the
./configure command to request not to build the docs).  And of course you can
see this as primarily a fault in how the build system defines its targets and
their dependencies.  But the simple fact is, had documentation generation been
built in rather than relying on 3rd-party tools, it would never have been an
issue, _and_ I'd have ended up having the documentation as well as just the
compiler executable and libraries.

Jan 02 2015
Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 4:29 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
Now, full credit to the rust community: they were immediately friendly and
helpful in advising me how to deal with this (you can pass a flag to the
./configure command to request not to build the docs).  And of course you can
see this as primarily a fault in how the build system defines its targets and
their dependencies.  But the simple fact is, had documentation generation been
built in rather than relying on 3rd-party tools, it would never have been an
issue, _and_ I'd have ended up having the documentation as well as just the
compiler executable and libraries.

Note that Doxygen is a third party tool, it also requires a bunch more third
party tools.

A friend of mine bemoaned using a piece of software on Linux that required not
one but multiple different and specific versions of Perl be installed in order
to even build the software.

Back in the early days of my compiler business, Microsoft shipped a linker on
the DOS disks. So all my users had a linker. Unfortunately, the linker versions
changed constantly. Eventually MS left the linker off of the DOS disks, but
would include it on the disks of all sorts of other software they sold. The
result was I couldn't rely on users having a linker, or any particular linker.
There was a blizzard of MS linkers in the wild, each with their own features
and
bugs. It was a support nightmare, consuming more and more of my time. I had
disks filled with my "linker collection" to test against.

Finally, I got my own linker (written by Bjorn Freeman-Benson). It wasn't the
greatest linker evar, but it worked, it was consistent, I knew what users had,
and I could fix bugs in it rather than find workarounds.

I learned over and over that controlling the full stack of what the user needed
was very practical.

Jan 03 2015
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 10:34, Andrei Alexandrescu via Digitalmars-d wrote:
On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. I don't think that's fair. AFAICS the only reason there's a "Stray ')'" issue to be concerned about is because the ) character is used to mark the end of a Ddoc macro. OK, I accept that it's rare that you get a ) without it being preceded by an opening ). But there are surely much rarer (in code) characters that could have been used, or the end-of-macro marker could have been chosen to be something completely unambiguous like$) or )$.  Jan 02 2015 "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes: On Thursday, 1 January 2015 at 20:15:55 UTC, Walter Bright wrote: A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not On the contrary, the complaint is that you can create your own macros and loose the semantics of the markup. I looked at the possibility to create a high quality javascript based front end to phobos documentation last year and the messy macro-markup/generated html killed the project before it got started. Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ LaTeX is not a standard. It is a quick'n'dirty macro-hack over TeX. If you want to mark up math, use HTML5's MathML and use MathJax for browsers that don't fully support it. http://www.w3.org/Math/ http://www.mathjax.org/sponsors/  Jan 02 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote: Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN)

which would be better coded as:

$(INTERVAL x .. y) INTERVAL=[$0$(RPAREN) See, this is my point.$(INTERVAL x .. y) is, to my mind, less clear to
read _in the source_ than [x, y).

If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-) "Serious flaw" sounds like a serious exaggeration. The notation "[x, y)" has unpaired parens. Any tool relying on pairing parens is going to have difficulty with it. This is exactly the kind of argument that diminishes the value of an otherwise great notion - that ddoc needs improvements addressing pain points with it. Andrei  Jan 02 2015 Ary Borenszweig <ary esperanto.org.ar> writes: On 12/31/14 4:50 PM, Andrei Alexandrescu wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (), as a simple way to expand macros: instead of$(MACRO arg1,
arg2) one can write MACRO arg1, arg2.

Andrei

1. Add "* foo" syntax for lists
2. Add **bold** and __bold__
3. Add *italic* and _italic_
4. Make some text automatically link to other D code. For example
std.algorithm.any would automatically link to
http://dlang.org/phobos/std_algorithm.html#.any . This must work for
types, functions, etc. If it doesn't resolve to a symbol, just put it
inside <code>...</code>
5. Make [text](url) denote a link.
6. Remove macros. Walter said: "Oh, Markdown can't be used to change the
typography, generate TOCs, etc.?". Well, you don't need to do those
things. Changing the typography will make it look ugly. You need a TOC?
That's the job of the documentation tool (the binary), not the
documentation syntax.

Basically, use Markdown :-)

Keep DDoc as it is now. Use it for your website if you want, to write
books or whatever. But for documentation don't use it as it is. There's
no need for macros. There's no need to generate JSON, XML, YAML, PDF or
anything other than HTML, which is quite universal and accessible now.

I repeat: keep DDoc, enhance it, use it as dog food for your websites,
books, etc. Use something simpler and less powerful for documenting
types and functions.

Jan 01 2015
"Dicebot" <public dicebot.lv> writes:
My top list of md shortcuts for "casual" documentation:

1. code

2. * lists

headers
3. =======

----------------------
4. | tables | that are  |
----------------------
| pretty | in source |
----------------------

Jan 01 2015
"Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 15:09:22 UTC, Dicebot wrote:
My top list of md shortcuts for "casual" documentation:

1. code

https://github.com/D-Programming-Language/dmd/pull/4228

That's by far my #1 syntax-wise, and since my implementation uses
the existing code, it will be relevant semantically too at some
point - when the code examples get cross-referencing, inline bits
will too, so we can link with that too (probably*).

The others aren't even really important to me at all; $(HEADER foo) or Foo: both look good enough for me. Tables might be nice, but overall aren't that big of a deal to me. * A potential problem running it through that D highlighter is not all code is necessarily D code. But most of it is and the rest still seems to work well enough - my xml tag test passed - so I think it is the biggest win for ddoc.  Jan 01 2015 Jacob Carlborg <doob me.com> writes: On 2015-01-01 16:09, Dicebot wrote: My top list of md shortcuts for "casual" documentation: 1. code 2. * lists headers 3. ======= I prefer the hashtag syntax: # header ## header -- /Jacob Carlborg  Jan 01 2015 ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes: On Thu, 01 Jan 2015 21:51:06 +0100 Jacob Carlborg via Digitalmars-d <digitalmars-d puremagic.com> wrote: On 2015-01-01 16:09, Dicebot wrote: My top list of md shortcuts for "casual" documentation: 1. code 2. * lists headers 3. =3D=3D=3D=3D=3D=3D=3D =20 I prefer the hashtag syntax: =20 # header =20 ## header there is nothing wrong in supporting both. ;-)  Jan 01 2015 Walter Bright <newshound2 digitalmars.com> writes: On 1/1/2015 7:09 AM, Dicebot wrote: headers 3. ======= headers:  Jan 01 2015 "Dicebot" <public dicebot.lv> writes: On Thursday, 1 January 2015 at 21:52:59 UTC, Walter Bright wrote: On 1/1/2015 7:09 AM, Dicebot wrote: headers 3. ======= headers: Wait what? It isn't formatted as <hX> as far as I can see. How exactly this is supposed to work?  Jan 06 2015 "Adam D. Ruppe" <destructionator gmail.com> writes: On Tuesday, 6 January 2015 at 15:00:06 UTC, Dicebot wrote: Wait what? It isn't formatted as <hX> as far as I can see. How exactly this is supposed to work? That makes a DDOC_SECTION. The default macro is DDOC_SECTION_H =$(B $0)$(BR)
DDOC_SECTION   = $0$(BR)$(BR) But if these macros were better, it could be a <header><hx>$0</hx></header> where the x is the right level.

I might spend a day revamping these macros eventually, the
default ones are so bad, they make poor html and hide some of
ddoc's own features.

Jan 06 2015
"Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Tuesday, 6 January 2015 at 15:13:00 UTC, Adam D. Ruppe wrote:
But if these macros were better, it could be a
<header><hx>$0</hx></header> where the x is the right level. The "header" element belongs in a sectioning element and the first heading in each section should be "h1": <section><h1>...</h1> <section><h1>...</h1> </section> </section>  Jan 06 2015 "Adam D. Ruppe" <destructionator gmail.com> writes: On Tuesday, 6 January 2015 at 15:17:32 UTC, Ola Fosheim Grøstad wrote: The "header" element belongs in a sectioning element Right, DDOC_SECTION is a <section> and the first element of it that ddoc outputs is is a DDOC_SECTION_H - a section header. We could debate the specific contents of it, h1 works for me but i kinda think h1 should be the outer aggregate name and then h2 if it is a nested member... but regardless, ddoc doesn't let you change the macros based on nesting anyway, but it does have the concept of grouped sections with headers.  Jan 06 2015 "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes: On Tuesday, 6 January 2015 at 15:31:52 UTC, Adam D. Ruppe wrote: could debate the specific contents of it, h1 works for me but i kinda think h1 should be the outer aggregate name and then h2 if it is a nested member... but regardless, ddoc doesn't let you change the macros based on nesting anyway, but it does have the concept of grouped sections with headers. Well, either way, if ddoc is worth fixing it would be a good idea to stick to HTML5 spec since they eventually managed to clean up the header mess of HTML4 (somewhat). http://www.w3.org/TR/html5/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements  Jan 06 2015 "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes: On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote: it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings.  Jan 01 2015 Ary Borenszweig <ary esperanto.org.ar> writes: On 1/1/15 1:23 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= <ola.fosheim.grostad+dlang gmail.com>" wrote: On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote: it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings. What's cross-library-indexing? You mean show documentation for many libraries at once?  Jan 01 2015 "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes: On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote: What's cross-library-indexing? You mean show documentation for many libraries at once? Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format.  Jan 01 2015 Ary Borenszweig <ary esperanto.org.ar> writes: On 1/1/15 2:35 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= <ola.fosheim.grostad+dlang gmail.com>" wrote: On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote: What's cross-library-indexing? You mean show documentation for many libraries at once? Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format. I really don't understand why you say that. I just started writing a documentation generator for the Crystal programming language. http://crystal-lang.org/api/ You can read about its features here: http://crystal-lang.org/2014/12/31/crystal-0.5.6-release.html Now, I go here http://dlang.org/phobos/std_file.html and I can't believe that after 10+ years of development, D documentation still doesn't have a basic feature like inter-linking between types (I even once submitted a PR but it wasn't accepted because other code was written on top of it and then the merge was hard to do). For example: http://dlang.org/phobos/std_file.html#.timeLastModified I should be able to click SysTime and go to that type definition. But, DDoc can generate Latex. Then, take a look at Rust. Guess what they use for their documentation? Markdown! Here's a web framework called Iron: http://ironframework.io/ Here are the API docs: http://ironframework.io/doc/iron/ Let's take a look at enum.Method: http://ironframework.io/doc/iron/method/enum.Method.html See that red "String" text? Click it and it takes you here: http://doc.rust-lang.org/nightly/collections/string/struct.String.html Wow! It took you to the String definition in an entirely different host! Back to Crystal's docs, below every method there's a "View Source" link that takes you to that code in GitHub. No such thing in D. Note that all of this was done with just Markdown (HTML) and by making the documentation generator understand and use the language as much as possible, something with DDoc doesn't do. I once submitted a PR to fix that, but it was ignored. I would suggest D to use a simple language to write the documentation, and then a powerful tool that understands the semantics of the language and allows you to generate good looking, easily browsable documentation. Neither JSON, XML, YAML or macros are needed for that.  Jan 01 2015 "JN" <666total wp.pl> writes: On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig wrote: and I can't believe that after 10+ years of development, D documentation still doesn't have a basic feature like inter-linking between types (I even once submitted a PR but it wasn't accepted because other code was written on top of it and then the merge was hard to do). For example: http://dlang.org/phobos/std_file.html#.timeLastModified I should be able to click SysTime and go to that type definition. Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/)  Jan 01 2015 "Dicebot" <public dicebot.lv> writes: On Thursday, 1 January 2015 at 18:24:47 UTC, JN wrote: I should be able to click SysTime and go to that type definition. Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/) vibe.d docs are generated using custom tool by Sonke, ddox, not the stock DDOC. Among other things it does automatically search for cross-references when generating the docs, no additional markup required afair.  Jan 01 2015 "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes: On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig wrote: I really don't understand why you say that. Because it is true? :-) Documents are old fashion, what you want is an interactive frontend to an information database. I would suggest D to use a simple language to write the documentation, and then a powerful tool that understands the You sometimes need to add annotations to enhance what can be deduced. That is obvious for dynamic languages (so you have JSDoc, which is kinda like JavaDoc/Doxygen), but it also holds for languages with static typing.  Jan 01 2015 "Adam D. Ruppe" <destructionator gmail.com> writes: On Thursday, 1 January 2015 at 20:00:12 UTC, Ola Fosheim Grøstad wrote: Because it is true? :-) Documents are old fashion, what you want is an interactive frontend to an information database. One thing I would like to do is add$(TAGS sorting, searching)
etc to functions where applicable which can be linked to
auto-generated lists and it can do categorization tables, etc.

I did a proof of concept of this years ago but there wasn't much
interest at the time.

(Arguably, now we could just group tagged functions into a
submodule instead...)

Jan 01 2015
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 7:01 AM, Ary Borenszweig wrote:
1. Add "* foo" syntax for lists

Currently ddoc ignores leading * so we'd need another character if at all.

2. Add **bold** and __bold__

How necessary are these?

3. Add *italic* and _italic_

Maybe these would be more often useful.

4. Make some text automatically link to other D code. For example
std.algorithm.any would automatically link to
http://dlang.org/phobos/std_algorithm.html#.any . This must work for
types, functions, etc. If it doesn't resolve to a symbol, just put it
inside <code>...</code>

Nice.

5. Make [text](url) denote a link.

Nice.

6. Remove macros.

We probably can't do that.

Thanks!

Andrei

Jan 02 2015
Jacob Carlborg <doob me.com> writes:
On 2015-01-02 10:10, Andrei Alexandrescu wrote:
On 1/1/15 7:01 AM, Ary Borenszweig wrote:
1. Add "* foo" syntax for lists

Currently ddoc ignores leading * so we'd need another character if at all.

A dash.

--
/Jacob Carlborg

Jan 02 2015
Jacob Carlborg <doob me.com> writes:
On 2014-12-31 20:50, Andrei Alexandrescu wrote:

One simple starter would be to allow one escape character, e.g. the
backtick (), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write MACRO arg1, arg2. I don't see how that would improve anything, at all. -- /Jacob Carlborg  Jan 01 2015 Jacob Carlborg <doob me.com> writes: On 2014-12-31 20:50, Andrei Alexandrescu wrote: In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that. I think the solution is to use Ddoc as it is today, with full support for Github flavored Markdown added and a couple of other enhancements. The reason is listed below: I'm not going to argue so much about the syntax since many others have already done so. The functionality that I feel is missing: * Automatically generating cross-references * Inhering documentation. Methods that override some other method should automatically inherit the documentation of the overridden method, unless there's already documentation present for that method or explicitly disable the inheritance with a command. * A list of summary with all symbols should be automatically generated for a module * Documentation for private symbols should be generated but hidden by default in the output with a button to show them * A nice tree view with all packages and modules with filter for all symbols * Automatically create links to the source code for each symbol. This could either be to syntax highlighted source code Ddoc generates or to Github. There could be a flag (or some other way) to specify which Github project to link to * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default The following should automatically be generated for a given class: * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg  Jan 01 2015 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/1/15 2:38 PM, Jacob Carlborg wrote: On 2014-12-31 20:50, Andrei Alexandrescu wrote: In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that. Sounds great, thanks. I think the solution is to use Ddoc as it is today, with full support for Github flavored Markdown added and a couple of other enhancements. Full support would probably break a lot of extant documentation. The reason is listed below: I'm not going to argue so much about the syntax since many others have already done so. The functionality that I feel is missing: * Automatically generating cross-references Nice. * Inhering documentation. Methods that override some other method should automatically inherit the documentation of the overridden method, unless there's already documentation present for that method or explicitly disable the inheritance with a command. Nice! * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? * Documentation for private symbols should be generated but hidden by default in the output with a button to show them Nice. * A nice tree view with all packages and modules with filter for all symbols This seems like a matter of styling, not functionality. * Automatically create links to the source code for each symbol. This could either be to syntax highlighted source code Ddoc generates or to Github. There could be a flag (or some other way) to specify which Github project to link to Nice. * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default Nice. The following should automatically be generated for a given class: * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable Looks like a great list, thanks. Andrei  Jan 02 2015 Jacob Carlborg <doob me.com> writes: On 2015-01-02 10:40, Andrei Alexandrescu wrote: * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? No, why would we do that? I want be able to easily generate good documentation. If something requires an extra step to make it better it will not be as easy. I also think it will be easier for Ddoc to do this than doing it in a postprocess step: * Ddoc will already have all the information available * The postprocessing tool will need to parse the output to get this information * If Ddoc is supposed to be designed for multiple output formats the postprocessing tool need to be able to handle that as well. Also, it should be possible to disable this if it's not desired. * A nice tree view with all packages and modules with filter for all symbols This seems like a matter of styling, not functionality. I don't see how this can be a matter of styling if it should support filtering. I'm thinking of something like the Scala documentation I linked to [1]. It has something more like a flat list with different sections. It doesn't matter if you call it styling of functionality ;) I still would like to see it in the default output. [1] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg  Jan 02 2015 "Mathias LANG" <geod24 gmail.com> writes: On Friday, 2 January 2015 at 09:40:45 UTC, Andrei Alexandrescu wrote: * Automatically generating cross-references Nice. https://github.com/rejectedsoftware/ddox/blob/master/README.md#ddox-documentation-engine I'm still wondering why it's not shipped with DMD. * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? Agree. It would break one of the goal of Ddoc (It does not repeat information that the compiler already knows from parsing the code.) Note that ddox also do that http://vibed.org/api/vibe.core.concurrency/ . It's not perfect, but you're sure it's always up to date, and is way more readable than what Phobos is currently doing with BOOKTABLE. * Documentation for private symbols should be generated but hidden by default in the output with a button to show them Nice. I don't see it being useful for Phobos, or any other library. Have one doc with the public API available, optionally another one for the framework/lib devs (but those often prefers the code). * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default Nice. Strongly agree for the constraints. For __FILE__ & __LINE__, what would it affects ? I can think of exception-related stuff, anything else ? Also, I was very puzzled with$(D) when I was looking for the
right way to use it. I think the answer is relevent to this
dicussion:
https://github.com/rejectedsoftware/vibe.d/pull/875

Most of the issues, IMO, are stylistic. We should firstly work on
improving the output, rather than introduce new syntax.

Also, documentation is much more subjective than code (just like
success and adult content :o) ). We could introduce control flags
to ensure some minima are met, examples that come to mind are:
--ddoc-werror (build failure on doc warning),
--ddoc-require=params,returns (require Params and Returns
sections to be defined, those can be empty for trivial functions),
--ddoc-document=public (require every public symbols to be
documented).

Jan 02 2015
Jacob Carlborg <doob me.com> writes:
On 2015-01-02 15:12, Mathias LANG wrote:

I don't see it being useful for Phobos, or any other library. Have one
doc with the public API available, optionally another one for the
framework/lib devs (but those often prefers the code).

I see that being useful for any open source library. I don't mind having
an option to enable/disable generating documentation for private symbols.

Strongly agree for the constraints. For __FILE__ & __LINE__, what would
it affects ? I can think of exception-related stuff, anything else ?

A perfect example where this is a big issue is the upcoming std.logger
[1]. It looks absolutely horrible. Every logging functions has five of
these arguments and in 99.99% of the cases you do not need to pass these
arguments manually.

[1] http://burner.github.io/phobos/phobos-prerelease/std_logger_core.html

--
/Jacob Carlborg

Jan 03 2015
"Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 22:38:05 UTC, Jacob Carlborg wrote:
That are just a couple of suggestions. Just take a look at some
existing documentation for other language and see what's
missing [1], [2].

[1]
http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html

[2]
http://www.scala-lang.org/api/current/#scala.collection.Iterable

To me Ddoc documentation is different from javadoc-flavored
documentation and rightfully so. Ddoc is module centered with
some nice introduction at the top and includes helpful unittest
examples, too. Where OO-centered reference documentation puts
comments to all classes and methods, Ddoc allows (and encourages)
documentation that can be read to learn about the module. You
know, I am your average troll, spending my time reading
documentation. Pure reference documents are no fun to read.

Jan 02 2015
"Martin Nowak" <code dawg.eu> writes:
On Wednesday, 31 December 2014 at 19:50:49 UTC, Andrei
Alexandrescu wrote:
Hello,

In wake of the recent discussions on improving ddoc syntax
we're looking at doing something about it. Please discuss any
ideas you might have here. Thanks!

Quite often pull requests for the changelog [0] contain
unbalanced parens.
Maybe we can replace some of the parens with indent level nesting?

Example:

$(BUGSTITLE Language Changes,$(LI $(RELATIVE_LINK2 asm-attributes, Asm statements can now be used in pure nothrow nogc trusted code.)) )$BUGSTITLE Language Changes
$LI$RELATIVE_LINK2 asm-attributes, Asm statements can now be
used in pure nothrow  nogc  trusted code.

An indented block is the last argument to a macro (BUGSTITLE).
A macro without parens has all of it's arguments on the same line.
Commas belong to the innermost macro (RELATIVE_LINK2).
Parens can still be used.

[0]:
https://github.com/D-Programming-Language/dlang.org/blob/master/changelog.dd

Jan 02 2015