On 9/14/2016 11:11 PM, Walter Bright wrote:
> On 9/14/2016 2:31 PM, Andrei Alexandrescu wrote:
>> The resulting look is alien too, as opposed to the more familiar $MACRO(a1, a2,
>> a3) or the CPP-style MACRO(a1, a2, a3).
>
> The $(MACRO a1, a2, a3) syntax comes from makefiles.

The original idea was to be able to write documentation without needing many macros, if any. Such as this I wrote recently:

/**
 * Provides a safe interface to the Posix stat() function.
 *
 * Detailed description that I didn't write for this function,
 * but this is where it goes.
 *
 * Another paragraph.
 *
 * Params:
 *	path = file name
 *	buf = stat instance to be filled in
 * Returns:
 *	0 for success, system errno for error
 */

I suspect that adding Markdown would help a lot (yes, I changed my mind about that). Also auto-detecting email addresses and urls and turning them into clickable links would help.

On 2016-09-14 22:14, Andrei Alexandrescu wrote:

> Why? -- Andrei

I've recently worked on a theme for Ddoc that will be used in TextMate. For convince I started by adding the CSS inline in the head tag. Turns out if you have CSS looking like this:

.foo {
  font-weight: bold;
  background-color: white;
}

Everything works perfectly fine. Then I added text color as well:

color: black;

Guess what happens? It cuts, it cuts everything after "color". The solution is to use a colon macro:

Macros:
  COLON = :

color$(COLON) black;

It took me quite a while and a lot of frustration until I figured that out. But I guess that's an inherit problem with a macro system.

That is what I'm missing from Ddoc:

* Inline source code for each symbol [1]. The [1] example both has a button to show the source code inline and a direct link to GitHub

* Link to GitHub for each symbol [1] and for the whole module. The way it's done now with $(PHOBOSSRC std/net/_isemail.d) is not standardized and feels like a hack. Why slashes and why the underscore? If anything it should be the fully qualified name. Ideally it should be automatic, or a compiler recognized macro that inserts the link

* Ddoc should organize symbols by visibility [2]
* Ddoc should generate index table [3]
* Ddoc should organize a module by symbol category [4]
* Add a way to inherit documentation from the parent class [5]

* Ddoc should give a list of inherited members [6]. JavaDoc does this by default [7]

* Consistent way of cross-referencing. Ideally one would just pass the fully qualified name (or local name for symbols in the same module) to a compiler recognized macro and it would generate the appropriate links

* An index page with all symbols, including a filter [8]. This is super convenient when you know the symbol to use but you need to double check how it's used or the behavior. I use it almost every day with Ruby

All this should be done within Ddoc without the need for any post processing.

In general I feel that Ddoc is too much focused on a generic macro system instead of focusing on being a good tool for writing documentation for code.

[1] http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-first

[2] https://issues.dlang.org/show_bug.cgi?id=11893
[3] https://issues.dlang.org/show_bug.cgi?id=11891
[4] https://issues.dlang.org/show_bug.cgi?id=11892
[5] https://issues.dlang.org/show_bug.cgi?id=10399
[6] https://issues.dlang.org/show_bug.cgi?id=7688

[7] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fdom%2FSimpleName.html

[8] http://ruby-doc.org/core-2.3.1

-- 
/Jacob Carlborg

On 15 September 2016 at 13:49, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/14/16 9:28 PM, Manu via Digitalmars-d wrote:
>>
>> Like, I really just don't care enough to try and understand ddoc
>> sufficiently to have a bag of tricks like those you demonstrated above
>> to workaround these issues. It's not a skill I *want* to possess,
>> rather, in this case, it's a skill I'm being forced into.
>> You're welcome to call me lazy, I'd suggest I'm being realistic.
>> Perhaps a phobos contributor will be required to work it out (as seems
>> to be a requirement for me right now), but normal programmers
>> wouldn't. In 7 years, I've never been motivated to find workarounds to
>> ddoc shortcomings before now, and now, it's only because people are
>> hassling me. There's no intrinsic motivation here... one reason I use
>> D is because I hate the C preprocessor ;)
>
>
> I don't see those workarounds to ddoc shortcomings. m4 and all macro systems I know of have similar idioms. It's the nature of macro processing. Are you simply saying you're familiar with other documentation tools and are not motivated to get into another one? That's entirely fair.

That's absolutely what I'm saying, but not only that, given that I'm
being forced into it now, I'm actively not enjoying it.
I understand it's a macro system, and I'm saying that's the problem as
I perceive it :)

I clearly recall when I learned doxygen. I generally liked it, and I
was motivated to populate my code with docs.
Perhaps there's an obvious counter-pressure in this case since I
already know doxygen, but I think that's insignificant compared to the
fact that I just don't like ddoc.
This macro system is not what I would have done, and it's just not
compelling. I don't want documentation-realted macro definitions in my
code. I also hate the paren spam.


>> If I had to suggest, I'd introduce doxygen style \tags alongside the macros, then when people try and type docs in the way they've been doing for decades, it'll just work, and they can get on with their code. Nobody likes writing documentation, it needs to have the minimum possible friction or people just won't.
>
>
> I have difficulty understanding this. I haven't looked at Doxygen in a long time and never really used it, but from what I see at https://www.stack.nl/~dimitri/doxygen/manual/commands.html it seems the \tags you refer to are just a form of macros. The syntax is different, i.e. you'd write \a hello whereas in html you'd write <i>hello</i>, in latex \textit{hello}, in ddoc $(I hello). It's a matter of syntax and though I agree syntax matters (and it would be nice to make ddoc's more configurable), is it right to assume you simply want a syntax you're more familiar with?

I think of those examples, doxygen is objectively the least annoying syntax! It's 2 bytes, and doesn't introduce delimiters or parens of any kind.

Sure, that's definitely an influence, I hate paren spam, but it's not all. If in practise I was able to make my docs be how I want as easily as I was able to the first time I encountered doxygen, I wouldn't be bothered. But I've had a number of contacts with ddoc now, and it's just not intuitive how to make my docs how I want, whereas with doxygen, I was walking within minutes, seconds even.

I think I have a sense of uneasy-ness that comes from my intuition
that macros are macros, and I don't know which ones are 'special', or
which are just macros.
Ie, some macros are obviously not actually macros, but keywords in disguise.
Doxygen says things like "\a word" (style this as an argument), ddoc
seems to be $(I word) (italic this), which says nothing about the
semantic meaning of the thing allowing styling to be deferred.
I refer to this page: https://dlang.org/spec/ddoc.html
There's nothing there that says how to style a template argument for
instance, it's all 'italic, big, small, bold' etc, and skimming other
ddoc code, I see people using raw styling like $(I ..) (as you just
demonstrated above).
At face value, it feels clumsy and poorly defined. I'm sure I'm
incorrect, but I just didn't have this same first-impression with
doxygen, or C#'s doco standard (they're the only 2 others I've used
before).

The only reference I've ever looked at for doxygen is this page:
https://www.stack.nl/~dimitri/doxygen/manual/commands.html
I never read another line from their manuals, everything else emerged
via osmosis, and I think osmosis is the correct way a programmer
should learn this stuff, which means it needs to be as obvious and
intuitive as possible.


> How do you mean people "type docs in the way they've been doing for decades"? Are you implying doxygen not only has been around for decades, but it's been some sort of ubiquitous standard? Honest question, I'm definitely not getting that.

Do you feel that doxygen is not a ubiquitous standard? It's been
around for like 20 years.
I can't think of any non-doxygen docs I interact with regularly other
than Microsoft docs... Maybe this is just a C/C++ ecosystem thing?


> Does this boil down to - if we replace the macro syntax with one closer to doxygen things will just click? (That may as well be the case.)

Well, I think the core of my uneasy-ness is that the macros have no
clear semantic meaning.
Obviously I can design my own set of macros that express my semantic
meaning... to hell with standards! ;)
Your prior post said "here's a bunch of macros I never leave home
without", that's exactly the problem as I see it.
I don't want too see ddoc macro definition blocks appearing at random
locations in my source code.

And I'll also remind you of my past criticism that my solution to porting C code to D, is to block delete the doxygen comment blocks rather than bothering to port them to D. If I had a reason to say what you said above "if we replace the macro syntax with one closer to doxygen...", this is that reason, but it's the fact that they're macros rather than keywords that makes me upset, so replacing the macros with a different syntax probably won't make me feel less uneasy.

Perhaps my uneasy-ness would subside if the list of 'builtins' (https://dlang.org/spec/ddoc.html) was more comprehensive (comparable to doxygen commands), and I never saw a ddoc macro definition in code anywhere. My gripe with the syntax would probably have passed without comment if that were the case and I would have just gotten used to it.

And don't get me wrong, I think it's absolutely fantastic that D has a built-in documentation system. I just don't really like it.

On 15 September 2016 at 16:44, Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/14/2016 11:11 PM, Walter Bright wrote:
>>
>> On 9/14/2016 2:31 PM, Andrei Alexandrescu wrote:
>>>
>>> The resulting look is alien too, as opposed to the more familiar
>>> $MACRO(a1, a2,
>>> a3) or the CPP-style MACRO(a1, a2, a3).
>>
>>
>> The $(MACRO a1, a2, a3) syntax comes from makefiles.
>
>
> The original idea was to be able to write documentation without needing many macros, if any. Such as this I wrote recently:
>
> /**
>  * Provides a safe interface to the Posix stat() function.
>  *
>  * Detailed description that I didn't write for this function,
>  * but this is where it goes.
>  *
>  * Another paragraph.
>  *
>  * Params:
>  *      path = file name
>  *      buf = stat instance to be filled in
>  * Returns:
>  *      0 for success, system errno for error
>  */
>
> I suspect that adding Markdown would help a lot (yes, I changed my mind about that). Also auto-detecting email addresses and urls and turning them into clickable links would help.

+1

Do we mind moving this discussion to the other topic I started actually on this topic?

It's slightly upsetting that this discussion about ddoc is more popular than the colour lib I spent months workinng on :(


On 15 September 2016 at 16:55, Jacob Carlborg via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 2016-09-14 22:14, Andrei Alexandrescu wrote:
>
>> Why? -- Andrei
>
>
> I've recently worked on a theme for Ddoc that will be used in TextMate. For convince I started by adding the CSS inline in the head tag. Turns out if you have CSS looking like this:
>
> .foo {
>   font-weight: bold;
>   background-color: white;
> }
>
> Everything works perfectly fine. Then I added text color as well:
>
> color: black;
>
> Guess what happens? It cuts, it cuts everything after "color". The solution is to use a colon macro:
>
> Macros:
>   COLON = :
>
> color$(COLON) black;
>
> It took me quite a while and a lot of frustration until I figured that out. But I guess that's an inherit problem with a macro system.
>
> That is what I'm missing from Ddoc:
>
> * Inline source code for each symbol [1]. The [1] example both has a button to show the source code inline and a direct link to GitHub
>
> * Link to GitHub for each symbol [1] and for the whole module. The way it's done now with $(PHOBOSSRC std/net/_isemail.d) is not standardized and feels like a hack. Why slashes and why the underscore? If anything it should be the fully qualified name. Ideally it should be automatic, or a compiler recognized macro that inserts the link
>
> * Ddoc should organize symbols by visibility [2]
> * Ddoc should generate index table [3]
> * Ddoc should organize a module by symbol category [4]
> * Add a way to inherit documentation from the parent class [5]
>
> * Ddoc should give a list of inherited members [6]. JavaDoc does this by default [7]
>
> * Consistent way of cross-referencing. Ideally one would just pass the fully qualified name (or local name for symbols in the same module) to a compiler recognized macro and it would generate the appropriate links
>
> * An index page with all symbols, including a filter [8]. This is super convenient when you know the symbol to use but you need to double check how it's used or the behavior. I use it almost every day with Ruby
>
> All this should be done within Ddoc without the need for any post processing.
>
> In general I feel that Ddoc is too much focused on a generic macro system instead of focusing on being a good tool for writing documentation for code.
>
> [1] http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-first
>
> [2] https://issues.dlang.org/show_bug.cgi?id=11893
> [3] https://issues.dlang.org/show_bug.cgi?id=11891
> [4] https://issues.dlang.org/show_bug.cgi?id=11892
> [5] https://issues.dlang.org/show_bug.cgi?id=10399
> [6] https://issues.dlang.org/show_bug.cgi?id=7688
>
> [7] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fdom%2FSimpleName.html
>
> [8] http://ruby-doc.org/core-2.3.1
>
> --
> /Jacob Carlborg

On 9/15/2016 12:06 AM, Manu via Digitalmars-d wrote:
> I think I have a sense of uneasy-ness that comes from my intuition
> that macros are macros, and I don't know which ones are 'special', or
> which are just macros.

That's easy, they are all just macros, and can all be redefined.

On Thursday, 15 September 2016 at 06:44:16 UTC, Walter Bright wrote:
> On 9/14/2016 11:11 PM, Walter Bright wrote:
>
> I suspect that adding Markdown would help a lot (yes, I changed my mind about that). Also auto-detecting email addresses and urls and turning them into clickable links would help.

I **really** love the pragmatism of this man!

;-)

/Paolo

On 15 September 2016 at 17:38, Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/15/2016 12:06 AM, Manu via Digitalmars-d wrote:
>>
>> I think I have a sense of uneasy-ness that comes from my intuition that macros are macros, and I don't know which ones are 'special', or which are just macros.
>
>
> That's easy, they are all just macros, and can all be redefined.

Yeah... I suspected this was the case ;)

On 2016-09-15 09:11, Manu via Digitalmars-d wrote:
> Do we mind moving this discussion to the other topic I started
> actually on this topic?
>
> It's slightly upsetting that this discussion about ddoc is more
> popular than the colour lib I spent months workinng on :(

Sorry.

Is it the "ddoc latex/formulas?" topic? That's the only recent topic by you related to ddoc. But I have no interest in either latex or formulas.

-- 
/Jacob Carlborg

Am Wed, 14 Sep 2016 23:44:16 -0700
schrieb Walter Bright <newshound2@digitalmars.com>:

> I suspect that adding Markdown would help a lot (yes, I changed my mind about that).

+1

-- 
Marco