On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
> Where it breaks down is when you have many nested tags, and you end with )))))

Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.

With Ddoc, I do this at the opening (, and see if the matching one is the closing ). If not, surprisingly, the match shown is the one that is erroneous.

https://github.com/DigitalMars/med/blob/master/src/med/search.d#L453

On Wednesday, January 31, 2018 18:58:29 Walter Bright via Digitalmars-d wrote:
> On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
> > Where it breaks down is when you have many nested tags, and you end with
> > )))))
> Long ago, I adjusted my text editor so that when the cursor is placed on
> ), the matching ( is found. Ditto for { }, [ ], < >, and
> #if/#elif/#else/#endif (!). It's been incredibly convenient.
>
> With Ddoc, I do this at the opening (, and see if the matching one is the closing ). If not, surprisingly, the match shown is the one that is erroneous.
>
> https://github.com/DigitalMars/med/blob/master/src/med/search.d#L453

vim does that and it's invaluable. It also makes it easy to hop between matching parens or braces, which is part of what drives me nuts about python. Because it doesn't have braces, it's harder to hop to the opposite end of a block.

Now, I think that it's still problematic when you end up with a bunch of parens in a row, since you tend to have to put your study it and put your cursor on each paren to understand what you're looking at, but having that highlighting definitely helps.

- Jonathan M Davis

On Thursday, 1 February 2018 at 01:23:38 UTC, Adam D. Ruppe wrote:
> Now, if a 5-character insertion requires 29 edit operations, what do you think the programmer is going to do? Keep up with it, or let the documentation stay slightly suboptimal and out-of-date because it is a hassle?

To be fair, I feel with you and all the tables I have created are formatted as good as DDoc allows, e.g.

https://github.com/dlang/phobos/blob/master/std/exception.d

Actually I prefer doing tables in Ddoc because it's a little easier (if you know all the macros)

> BTW, I also hate any syntax that requires editing every line. Again, it goes back to that linear vs constant time edit. I just copy/pasted that from the website. Using bbcode or html or ddoc or adrdox, you just surround it with some tag like I did there. Even indenting it is not really necessary to make it legible and functional (though like every editor makes that simple anyway).
>
> I prefer markdown's ``` blocks to the leading for spaces primarily for this reason, though adding language tags is a secondary benefit to that.
>
> This is also why I friggen hate comments with leading stars:
>
> /*
>  * why write all
>  * this leading crap?
>  */
>
> /*
>     This is so much better
> */

Same here.
We recently added this to the DStyle:

https://dlang.org/dstyle.html#phobos_documentation
https://github.com/dlang/dlang.org/pull/2129

So, new Phobos code will be written without stars.

> Edit those without using editor macros. Barf. And if you are willing to use editor macros, the other justification for it - making the comment look different than code - disappears since if your editor is fancy enough to understand that leading * crap and automatically reformat it, it could just as well syntax highlight it in some way (including displaying leading stars without saving them to the file!)
>
>> I wouldn't expect `...` to produce a link; it should just be formatted differently (typically in monospace font) to indicate that it's a code snippet.

It tells quite a bit about the complexity of Ddoc that I had to add support for -D to run.dlang.io ...

>> Using [...] syntax for links makes more sense to me, even though personally, I really prefer to just write plain ole text and paste the URL in its own indented block:
>>
>> 	http://example.nowhere.edu/blah/blah/blah
>
> adrdox recognizes urls and I like writing them like that when I actually write a url.... but the benefit of [reference] is that it doesn't require an actual url. It is just a symbol, in scope even.

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


https://github.com/dlang/dmd/pull/7043

On Thursday, 1 February 2018 at 01:27:43 UTC, Adam D. Ruppe wrote:
> On Wednesday, 31 January 2018 at 15:40:04 UTC, Jakub Łabaj wrote:
>> What is the current state of the art of writing inline code in the documentation?
>
> To give you a quick answer, the tide is going toward ``. You should probably just use it in most cases as long as the code fits on a single line. If it is a multi-line sample, use ddoc's `---` brackets or a documented unittest instead.
>
> If you do want cross referencing, don't rely on $(D) nor `` to do it. Instead, there's a $(REF) macro in std.ddoc to use. Do NOT combine them:
>
> See also: $(REF std,string,lowerCase) // correct (i think)*
> See also: `$(REF ...)` // wrong, do not use `` here
>
>
> * I don't remember the actual syntax for that ref macro.

It's: $(REF lowerCase, std,string) or $(REF_ALTTEXT alternative text, lowerCase, std,string)

On Thursday, 1 February 2018 at 01:23:38 UTC, Adam D. Ruppe wrote:
> In CS terms, it turned a constant-time edit into a O(n) operation, scaling linearly with the number of rows.

Well, there's line-oriented tabular data format, forgot the name (re*-something), it looks like definition list:
---
Member: front
Description: gets front element
Member: popFront
Description: pops front element
Member: empty
Description: checks if empty
---

Is logically a table:

|Member  |Description|
+--------+-----------+
|front   |gets front element|
+--------+----------
|popFront|pops front element|
+--------+----------
|empty   |checks if empty|
--------------------

I can see that ddoc is a pretty hot topic here ;)

On Thursday, 1 February 2018 at 01:27:43 UTC, Adam D. Ruppe wrote:
> To give you a quick answer, the tide is going toward ``. You should probably just use it in most cases as long as the code fits on a single line. If it is a multi-line sample, use ddoc's `---` brackets or a documented unittest instead.

Thank you for the answer and very thorough explanation. Seems like the Wiki contains up-to-date information then.

On 1/31/18 9:58 PM, Walter Bright wrote:
> On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
>> Where it breaks down is when you have many nested tags, and you end with )))))
> 
> Long ago, I adjusted my text editor so that when the cursor is placed on ), the matching ( is found. Ditto for { }, [ ], < >, and #if/#elif/#else/#endif (!). It's been incredibly convenient.

This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.

When I'm reviewing a PR, I don't see the matching as easily. Even with an editor tool, it's a lot of parentheses to look at.

An example:

https://github.com/dlang/phobos/pull/5452

Introduced:

https://github.com/dlang/phobos/pull/4027

Take a look at the original PR and see how the parentheses look fine, very very hard to see that there is a problem.

-Steve

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

On Thu, Feb 01, 2018 at 09:09:28AM -0500, Steven Schveighoffer via Digitalmars-d wrote:
> On 1/31/18 9:58 PM, Walter Bright wrote:
> > On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:
> > > Where it breaks down is when you have many nested tags, and you
> > > end with )))))
> > 
> > Long ago, I adjusted my text editor so that when the cursor is
> > placed on), the matching ( is found. Ditto for { }, [ ], < >, and
> > #if/#elif/#else/#endif (!). It's been incredibly convenient.
> 
> This has literally been in vim since I started using it, what, 15 years ago?  It doesn't matter.

Yeah, vim has had this *by default* since who knows how long ago.  I've been surprised that things like this still bother people today -- non-vim users are missing out!


> When I'm reviewing a PR, I don't see the matching as easily. Even with an editor tool, it's a lot of parentheses to look at.
[...]

This is one reason I'm not a fan of browser-based tools. They're essentially just 90's technology in fancy dress.  For reviewing complicated PRs, I still prefer just fetching the git branch directly into my local Phobos fork and using vim to look through the code.  Seb's git scripts for fetching/pushing PRs is pretty useful for this; see the Maintainer's guidelines page on the wiki.


T

-- 
Valentine's Day: an occasion for florists to reach into the wallets of nominal lovers in dire need of being reminded to profess their hypothetical love for their long-forgotten.

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.

> Same here.
> We recently added this to the DStyle:

Yeah, I saw. 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'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

Well, the url recognition is nice, but my main point there was actually that xrefs ideally aren't urls at all for a few reasons.

But still, it is better than nothing, no doubt.