On 2016-09-15 14:54, Andrei Alexandrescu wrote:

> Yah, this is terrible (it happens with http: all the time). We need to
> suppress the special meaning of ":" to only the cases when it's preceded
> by only one word and followed by a newline, e,g, "\ncolor:\n".

It's useful for many of the sections to allow the section name on the same line as the content:

/// Returns: some useful value
int foo();

See the Ddoc documentation for more examples [1].

> Can this be done by defining the expansion macros appropriately?

What are "the expansion macros" ?

> Slashes are tolerable. The underscore I agree it's a quirk.

There are several (other) problems:

* How do I know I should use slashes? There's no documentation
* It's not a standard macro. If it's not here [2] nobody will find it or use it

> That's a fair assessment, and an actionable one.

Perhaps the current implementation of Ddoc could be moved to a separate tool that would focus on being a macro system. That can still be used for the site and other documents. Ddoc in the compiler could be improved to be a better tool for documenting code. I think these are two separate use cases that might not be best accomplished with the same tool.

[1] http://dlang.org/spec/ddoc.html#standard_srction
[2] http://dlang.org/spec/ddoc.html#predefined_macros

-- 
/Jacob Carlborg

On 2016-09-15 16:45, Andrei Alexandrescu wrote:

> Glad to hear that. It becomes a matter of improving the default-provided
> macros and/or distribute some .ddoc batteries.
>
> Jacob, I'd also like to thank for the great constructive ideas for
> improving things and for formulating them as enhancement requests on
> bugsilla. This is the kind of communication that pushes things forward.

The oldest bugzilla issue I referred to is more than four years old and this is not the first discussion on the topic :(

-- 
/Jacob Carlborg

On 09/15/2016 02:34 PM, Jacob Carlborg wrote:
> On 2016-09-15 14:54, Andrei Alexandrescu wrote:
>
>> Yah, this is terrible (it happens with http: all the time). We need to
>> suppress the special meaning of ":" to only the cases when it's preceded
>> by only one word and followed by a newline, e,g, "\ncolor:\n".
>
> It's useful for many of the sections to allow the section name on the
> same line as the content:
>
> /// Returns: some useful value
> int foo();
>
> See the Ddoc documentation for more examples [1].

That's fine because "Returns" is special-cased. Random words at the beginning of a line followed by ":" should not receive special treatment.

>> Can this be done by defining the expansion macros appropriately?
>
> What are "the expansion macros" ?

Those DDOC_XXX things that are used for formatting declarations.

>> Slashes are tolerable. The underscore I agree it's a quirk.
>
> There are several (other) problems:
>
> * How do I know I should use slashes? There's no documentation

"Monkey see, monkey do." :o)

> * It's not a standard macro. If it's not here [2] nobody will find it or
> use it

Guess we can improve the (d)docs.

>> That's a fair assessment, and an actionable one.
>
> Perhaps the current implementation of Ddoc could be moved to a separate
> tool that would focus on being a macro system. That can still be used
> for the site and other documents. Ddoc in the compiler could be improved
> to be a better tool for documenting code. I think these are two separate
> use cases that might not be best accomplished with the same tool.

That'd be neat. As always, somebody's got to do it...


Andrei

On Thursday, 15 September 2016 at 09:46:07 UTC, Patrick Schluter wrote:
> There are also some niceties like auto brief and autoreferencing (when a symbol is written in a text will be clickable if its body was reachable during generation of the doc).

Not only that, by using tag files [1] Doxygen even generates clickable symbols to third party libraries and other online documentation, without having access to the respective code.

[1] http://www.stack.nl/~dimitri/doxygen/manual/config.html#config_external

Started a new thread on this, "Ddoc macro syntax". Please direct further discussion there.

On 9/15/2016 7:37 AM, Jacob Carlborg wrote:
> Yeah, if you already have defined all the standard ddoc macros because the
> default styling is not useful at all.

The default styling was set up to produce legible output while not requiring any configuration file, nor a .css style file nor any knowledge of HTML at all.

On 9/15/2016 4:59 AM, Nemanja Boric wrote:
> On Thursday, 15 September 2016 at 09:45:26 UTC, Marco Leise wrote:
>> 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).
>>
>
>
> https://github.com/kiith-sa/harbored-mod provides support for mixing ddoc and
> markdown. That's what we're using, and it's nice (especially because docs in
> source files look very close to generated ones), but it would be nicer if we
> could just use dmd for that, of course.

It looks like you've done some great work with this! And Boost licensed, too! I think we can leverage this for Ddoc markdown support. Thanks!

On 2016-09-15 20:55, Andrei Alexandrescu wrote:

> That's fine because "Returns" is special-cased. Random words at the
> beginning of a line followed by ":" should not receive special treatment.

Ah, so you mean all non-standard non-special sections? Basically any section that is not listed in the ddoc documentation.

> Those DDOC_XXX things that are used for formatting declarations.

Hmm, I don't think there's a DDOC_ macro that evaluates to the full source code a given symbol. For a function that would include the source code of the body.

> Guess we can improve the (d)docs.

But then we need to have a standardized macro for that.

> That'd be neat. As always, somebody's got to do it...

As always.

-- 
/Jacob Carlborg

On 2016-09-16 02:02, Walter Bright wrote:

> The default styling was set up to produce legible output while not
> requiring any configuration file, nor a .css style file nor any
> knowledge of HTML at all.

I don't see how that's relevant. Currently one needs to have knowledge of HTML and CSS because the default output is not usable.

With Yard (documentation generator for Ruby) one just invokes "yard -f html -o output intput.rb" and it generates all files and put them into "output". The result looks something like this [1].

How is that requiring any HTML or CSS knowledge?

[1] http://www.rubydoc.info/gems/rails-bootstrap-helpers/0.1.0/RailsBootstrapHelpers/Helpers/ButtonHelper

-- 
/Jacob Carlborg

On Monday, 12 September 2016 at 04:14:27 UTC, Manu wrote:
> I think I'm about as happy with my colour lib as I'm going to be. It really needs reviews.

I don't know enough about colors and what people do with it to give you helpful feedback, but I was wondering if you had looked at the (auto) vectorization of the code.
I see some matrix math code, which perhaps would benefit from LDC's @fastmath (or similar). It's just a thought. You can shoot me some example that you think should vectorize.

Anyway, I think you are mostly interested in API feedback, implementation optimization can come later.

(others: let's stop depressing Manu further and move all ddoc and other irrelevant discussions to other topics! :)