On Thu, Feb 01, 2018 at 05:33:21PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Thursday, 1 February 2018 at 06:18:52 UTC, Seb wrote:
> > To be fair, I feel with you and all the tables I have created are formatted as good as DDoc allows, e.g.
> 
> Yeah, that's not bad, really. I think that's actually significantly better than the Markdown table syntax - adding a new function or category there is pretty easy and it is legible enough in the source.

I still prefer Markdown table syntax.  But then again, I hardly ever need to put tables in my ddocs anyway, so perhaps that's just an uninformed opinion.


> [...] Actually, I saw a debate over /** */ vs /++ +/ too, and I'm pretty firmly on the /++ +/ side of it. Almost every time I write docs and do /** or even ///, I regret it because I want to change it to /++ later anyway so I can have commented code samples in the docs.
[...]

I actually like the /** */ syntax, with the stars that horrify you so much. :-D  Mainly because vim automatically formats them for me, so I never actually have to fiddle with the stars myself, and I do like long block comments being clearly standing out from the rest of the code.

As far as nested comments are concerned, I'm a firm believer in ddoc'd unittests, so I hardly ever bother with inline code examples, much less ones that need comments, and pretty much never ones that need block comments.

I do agree about ///, though.  Except for `/// ditto`, I almost invariably regret writing /// anywhere because they almost always need to be expanded into /** */ later on.  They're convenient for when I'm too lazy to write docs for enum members, but when polishing up docs, they basically always need to turn into /** */. So they're good for laziness, but not much more.


T

-- 
"Computer Science is no more about computers than astronomy is about telescopes." -- E.W. Dijkstra

On Thursday, 1 February 2018 at 19:21:52 UTC, H. S. Teoh wrote:
> As far as nested comments are concerned, I'm a firm believer in ddoc'd unittests, so I hardly ever bother with inline code examples, much less ones that need comments, and pretty much never ones that need block comments.

I use the documented unittests too, but they do have some pretty big limits: it is hard to embed them around explanatory text and actually using them as tests has a few limits:

* the unittest is not fully isolated, but users will copy/paste them into separate code. It may pass the test because of, for example, an import outside the test, but then fail to compile for the end user.

* automated tests are designed for automation and resiliancy, but good examples are designed for interactivity and tinkering by the user. They are almost opposite in purpose! (even the above goes in - a unittest tests a unit... a good example shows how to put the pieces together)

* unittests with a main function are a little wonky, but you can make it work.


I still kinda like it... but I think it is actually overrated.

On Thursday, 1 February 2018 at 12:06:44 UTC, Kagamin wrote:
> Well, there's line-oriented tabular data format, forgot the name (re*-something), it looks like definition list:

What bugs me with that sample is that the headers are repeated a lot... but it isn't bad.

But re* sounds like maybe restructuredText which I borrowed some ideas from too.

On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis wrote:
> Personally, I hate markdown, because it makes certain syntax magical - e.g. it's not uncommon that a commit message ends up looking bad when github uses it as the message for a PR, because some piece of code contained * or some other piece of syntax that markdown decides to do something magical with.

Yeah.

> I _much_ prefer the explicit syntax used by ddoc, so I can't say that I'm at all happy at the idea of markdown syntax being added to ddoc.

I agree, which is why adrdox only has a few magic syntaxes at top level and they are in places where I think it is more important to be extremely convenient (like cross-linking*).

But, at the same time, some special syntax can be REALLY nice. So I went with the hybrid approach: certain ddoc macro blocks actually run magic syntax:

$(LIST
  * List item here
  * another list item
  * third list item
)

The bracket clearly indicates that you want to opt-in to the special syntax, then you get to use that syntax for a while for the convenience. Another benefit is you can add other tweaks like class names for the HTML inside the bracket since there is a spot for that.

But anyway, the bracket also lets me use different syntaxes or reuse the same in a few places and generate different things. And BTW it is worth noting that ddoc ALREADY has a little bit of this: see the "Params:" section!


* BTW I almost wanted that syntax to be a bit uglier so you can embed it in code samples too unambiguously but that made me use it less instead of more...

> IMHO, the main problem with ddoc for documentation is that it doesn't automatically handle stuff like cross-links, and it fundamentally can't, because to do that properly, you have to generate all of the docs at once with a standard layout for where everything goes so that the links can link to stuff.

Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it.

Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.

On Thursday, 1 February 2018 at 14:51:41 UTC, ag0aep6g wrote:
> On 02/01/2018 07:18 AM, Seb wrote:
>> It tells quite a bit about the complexity of Ddoc that I had to add support for -D to run.dlang.io ...
> [...]
>> I'm not a fan of Ddoc by any means, but that has been fixed in Ddoc does this too now: https://run.dlang.io/is/75Z55o
>
> Uhh, is it a good idea to generate documentation on run.dlang.io? Isn't this an open invitation for XSS?
>
> Simple example, one can replace all links on the page with malicious ones:
> https://run.dlang.io/is/wYLpVx

I don't think it's a big problem as user needs to explicitly approve the code by hitting Run.
Also all the other Web editors (JSBin, JSFiddle etc.) allow you to do the same and even load the HTML + JS when you open the page.

Nevertheless, I added the "sandbox" feature of IFrames:

https://www.html5rocks.com/en/tutorials/security/sandboxed-iframes

-> now even any kind of JS code can't be executed.
Thanks!

On Friday, February 02, 2018 15:12:45 Adam D. Ruppe via Digitalmars-d wrote:
> On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
> > IMHO, the main problem with ddoc for documentation is that it doesn't automatically handle stuff like cross-links, and it fundamentally can't, because to do that properly, you have to generate all of the docs at once with a standard layout for where everything goes so that the links can link to stuff.
>
> Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it.
>
> Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.

I thought about that, but it falls flat on its face as soon as not all of the user-defined types are from the library being documented. The simplest example would be if I were to publish my own library but it used types from Phobos in its API. Turning those types into links would then try to link to my project's documentation, which wouldn't work. Best case, I could create redirects to the Phobos docs, so that might work, but it gets messy fast, and any types from 3rd party libraries which were used in the API would have the same problem. Somehow, the links would have to be made to work regardless of whether the types were part of the project being documented.

- Jonathan M Davis

On Fri, Feb 02, 2018 at 10:49:18AM -0700, Jonathan M Davis via Digitalmars-d wrote:
> On Friday, February 02, 2018 15:12:45 Adam D. Ruppe via Digitalmars-d wrote:
> > On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
> > > IMHO, the main problem with ddoc for documentation is that it doesn't automatically handle stuff like cross-links, and it fundamentally can't, because to do that properly, you have to generate all of the docs at once with a standard layout for where everything goes so that the links can link to stuff.
> >
> > Well, maybe, it could do something like adrdox's symbol lookup but instead of generating a link directly, it could replace it with $(REF) and let the macro definitions handle it.
> >
> > Wouldn't be perfect tho, that macro is clunky to use and define because it doesn't know all the details, but it would be a move up from what we have, and may even work inside code examples.
> 
> I thought about that, but it falls flat on its face as soon as not all of the user-defined types are from the library being documented. The simplest example would be if I were to publish my own library but it used types from Phobos in its API. Turning those types into links would then try to link to my project's documentation, which wouldn't work. Best case, I could create redirects to the Phobos docs, so that might work, but it gets messy fast, and any types from 3rd party libraries which were used in the API would have the same problem. Somehow, the links would have to be made to work regardless of whether the types were part of the project being documented.
[...]

In an ideal world, you wouldn't need to encode any of this stuff inside a ddoc comment.  Since ddoc comments are processed by the compiler, and the compiler has all of the information necessary to resolve identifiers, arguably all that *should* be needed is just a way to indicate in the docs, "this word is an identifier", and the compiler would figure out what it's referring to, perhaps expand it into a fully-qualified name like std.range.primitives.isInputRange.  Then this can be handed to a stylesheet that would turn it into a link of some sort.

Cluttering ddoc comments with URLs (or, as a proxy, macros containing information specific to URLs) that, arguably, the code itself shouldn't depend on, is something I have ideological issues with.  It's one thing to refer to a full URL to some online reference like a technical spec that's unchanging and, ostensibly, will always be out there; it's quite something else to explicitly spell out links to a particular symbol using a hard-coded path that can change any time.  E.g., today I may link to MyType as:

	$(LINK $(WEBROOT)/mypackage/mymod.html#MyType)

but tomorrow I may have a major refactoring and now I have to change
*all* such links to:

	$(LINK $(WEBROOT)/mynewpackage/newsubpackage/newmod.html#MyType)

instead, whereas the code itself actually doesn't need to change at all, because the compiler already knows where's the new location of the symbol, using standard identifier resolution.

Why can't I just write `[MyType]` (or whatever other syntax you prefer), and let the compiler figure out what the right fully-qualified name is? Once the compiler figures it out, the stylesheet takes care of turning it into a HTML link or the equivalent in whatever other output format you may be using.

On a higher level, even explicit links to symbols in Phobos docs are a bad idea.  What if 5 months later we decide to move dlang.org/phobos to dlang.org/docs/phobos?  Or if a Phobos refactoring moves a symbol to another module?  Any explicit URLs in user ddoc comments will break, and will have to be updated *one-by-one*.  Whereas if we let the compiler do its job, the worst that would happen is we update the stylesheet to point to dlang.org/docs/phobos/* instead of dlang.org/phobos/*, and *all* links in generated ddocs will be automatically corrected. Any change in the path to the symbol's doc will already have been resolved by the compiler -- if your code compiles at all.

tl;dr: I think anything more than plain old markup saying "this is a symbol that needs a link" in a doc comment is a bad idea.  Ddoc comments shouldn't be replicating the job of the compiler, and that poorly.


T

-- 
If creativity is stifled by rigid discipline, then it is not true creativity.

On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
> In an ideal world, you wouldn't need to encode any of this stuff inside a ddoc comment.

Well, that's what the Phobos REF macro does... sort of. You write $(REF symbolName, std, module) and the macro figures out the link. Though, even that macro is based on the url structure on dlang.org... it separates package arguments because it needs to $2_$3.html#$1 which doesn't match any generator. But it is a heck of a lot better than the old way of $(LINK2 std_string.html, std.string) which is just plain broken (and btw a few of those are still there :( ).

>  Since ddoc comments are processed by the compiler, and the compiler has all of the information necessary to resolve identifiers, arguably all that *should* be needed is just a way to indicate in the docs, "this word is an identifier", and the compiler would figure out what it's referring to, perhaps expand it into a fully-qualified name like std.range.primitives.isInputRange.

Right, this is exactly what adrdox does and it has been a smashing success to me. It'd be nice if ddoc did it too (at least so I don't have to deal with so many merge conflicts on the broken phobos source links!)

On Fri, Feb 02, 2018 at 07:46:51PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
> > In an ideal world, you wouldn't need to encode any of this stuff inside a ddoc comment.
> 
> Well, that's what the Phobos REF macro does... sort of. You write $(REF symbolName, std, module) and the macro figures out the link. Though, even that macro is based on the url structure on dlang.org...
[...]

Well exactly, and that's the problem. The macro arguments require knowledge of the URL structure on dlang.org.  And also knowledge of the FQN of the symbol. When the FQN changes, you have to update *every link* that refers to that symbol.  That's like coding in the bad ole days before encapsulation was a common practice. Everything depended on everything else, and changing one small thing causes a ripple effect that requires touching the rest of the code in 100 different places.

We should be leveraging what the compiler is already capable of doing, and keep the docs agnostic of the nitty-gritty details of the symbol's FQN or where it might reside in the URL tree.  It's plain and simple encapsulation, as applied to docs.


[...]
> >  Since ddoc comments are processed by the compiler, and the compiler
> >  has all of the information necessary to resolve identifiers,
> >  arguably all that *should* be needed is just a way to indicate in
> >  the docs, "this word is an identifier", and the compiler would
> >  figure out what it's referring to, perhaps expand it into a
> >  fully-qualified name like std.range.primitives.isInputRange.
> 
> Right, this is exactly what adrdox does and it has been a smashing success to me. It'd be nice if ddoc did it too (at least so I don't have to deal with so many merge conflicts on the broken phobos source links!)
[...]

This is the kind of thing you should be promoting to Andrei to convince him that dpldocs is better. ;-)


T

-- 
Today's society is one of specialization: as you grow, you learn more and more about less and less. Eventually, you know everything about nothing.

On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:
> This is the kind of thing you should be promoting to Andrei to convince him that dpldocs is better. ;-)

I've laid out my arguments several times, including this point. Actually, $(REF) was introduced after I made the argument, so it is a slight win, though ddoc, over the last two years, has barely caught up to what I was able to accomplish independently in two weeks.