digitalmars.D - Inline code in the docs - the correct way
- Jakub =?UTF-8?B?xYFhYmFq?= (15/15) Jan 31 2018 What is the current state of the art of writing inline code in
- H. S. Teoh (21/40) Jan 31 2018 AFAIK, backticks is preferred because $(D ...) syntax is noisier, and
- Adam D. Ruppe (6/9) Jan 31 2018 No, they aren't. The `` is different in several ways including
- H. S. Teoh (16/26) Jan 31 2018 Coming from you, I'm a little surprised. Weren't you one of the people
- Adam D. Ruppe (47/49) Jan 31 2018 $(H1 Rebuttal)
- H. S. Teoh (60/106) Jan 31 2018 Then I guess we differ on this point. While I think the ddoc macro
- Adam D. Ruppe (163/188) Jan 31 2018 FYI I am changing the subject line with this post since it is
- Seb (16/57) Jan 31 2018 To be fair, I feel with you and all the tables I have created are
- ag0aep6g (6/10) Feb 01 2018 Uhh, is it a good idea to generate documentation on run.dlang.io? Isn't
- Seb (9/20) Feb 02 2018 I don't think it's a big problem as user needs to explicitly
- Adam D. Ruppe (13/19) Feb 01 2018 Yeah, that's not bad, really. I think that's actually
- H. S. Teoh (22/33) Feb 01 2018 I still prefer Markdown table syntax. But then again, I hardly ever
- Adam D. Ruppe (16/20) Feb 02 2018 I use the documented unittests too, but they do have some pretty
- Kagamin (20/22) Feb 01 2018 Well, there's line-oriented tabular data format, forgot the name
- Adam D. Ruppe (5/7) Feb 02 2018 What bugs me with that sample is that the headers are repeated a
- Kagamin (5/9) Feb 03 2018 Yeah, the moment I scrolled the table header out of sight I can't
- Steven Schveighoffer (6/12) Jan 31 2018 Where it breaks down is when you have many nested tags, and you end with...
- Walter Bright (7/8) Jan 31 2018 Long ago, I adjusted my text editor so that when the cursor is placed on...
- Jonathan M Davis (11/21) Jan 31 2018 vim does that and it's invaluable. It also makes it easy to hop between
- Steven Schveighoffer (12/19) Feb 01 2018 This has literally been in vim since I started using it, what, 15 years
- H. S. Teoh (16/29) Feb 01 2018 Yeah, vim has had this *by default* since who knows how long ago. I've
- Walter Bright (3/14) Feb 02 2018 True, but that applies to anything with a block structure.
- Steven Schveighoffer (10/27) Feb 04 2018 Sure, I also have a difficult time with loads of parentheses in function...
- H. S. Teoh (11/17) Feb 04 2018 Wait till you see Lisp code. :-P
- Seb (11/25) Feb 04 2018 Yeah DMD emits those warnings and until recently -w with warnings
- Steven Schveighoffer (8/15) Feb 05 2018 I still have nightmares from my scheme class in college... Literally the...
- H. S. Teoh (16/33) Feb 05 2018 [...]
- bachmeier (16/48) Feb 05 2018 It's common in Scheme/Racket to use square brackets for nested
- Timon Gehr (2/16) Feb 05 2018 I additionally use: https://www.emacswiki.org/emacs/RainbowDelimiters
- Patrick Schluter (13/31) Feb 05 2018 When I programmed AutoLISP extension in AutoCAD I would use
- H. S. Teoh (8/21) Feb 05 2018 That's also my personal preference. Unfortunately, such practice is
- Walter Bright (4/20) Feb 04 2018 So I see. I wonder when that was added to vim. I put it in MicroEmacs in...
- Steven Schveighoffer (10/32) Feb 05 2018 I should clarify -- the matching parentheses feature has been in vim
- Jonathan M Davis (21/47) Jan 31 2018 Yeah. Tables are generally ugly, though they're also not super-common in
- Adam D. Ruppe (32/45) Feb 02 2018 Yeah.
- Jonathan M Davis (11/23) Feb 02 2018 I thought about that, but it falls flat on its face as soon as not all o...
- H. S. Teoh (48/74) Feb 02 2018 [...]
- Adam D. Ruppe (13/22) Feb 02 2018 Well, that's what the Phobos REF macro does... sort of. You write
- H. S. Teoh (20/38) Feb 02 2018 [...]
- Adam D. Ruppe (6/8) Feb 02 2018 I've laid out my arguments several times, including this point.
- Adam D. Ruppe (11/14) Feb 02 2018 I'm updating my fork now and check out this merge conflict:
- Seb (5/19) Feb 03 2018 I think that would only work if we drop the ddoc of phobos
- Adam D. Ruppe (18/22) Feb 03 2018 I could live with either :P
- Seb (7/21) Feb 03 2018 Have you thought of simply postprocessing REF_ALTTEXT for your
- Adam D. Ruppe (24/26) Feb 03 2018 It actually supports the macro, so I could just keep the upstream
- H. S. Teoh (14/27) Feb 03 2018 +1000. That misfeature has been continually plaguing us ever since it
- H. S. Teoh (9/18) Feb 03 2018 [...]
- Adam D. Ruppe (5/7) Feb 03 2018 Whelp, g'luck. I've tried to null out the macro before, maybe
- H. S. Teoh (9/17) Feb 03 2018 Shh! The plan is, after this PR gets merged, it becomes easier to turn
- Adam D. Ruppe (11/13) Jan 31 2018 To give you a quick answer, the tide is going toward ``. You
- Seb (3/17) Feb 01 2018 It's: $(REF lowerCase, std,string) or $(REF_ALTTEXT alternative
- Jakub =?UTF-8?B?xYFhYmFq?= (4/8) Feb 01 2018 Thank you for the answer and very thorough explanation. Seems
What is the current state of the art of writing inline code in the documentation? Wiki says "use `...` instead of $(D ...)": https://wiki.dlang.org/Contributing_to_Phobos#Documentation_style. Some arguments made here: https://github.com/dlang/phobos/pull/5183#issuecomment-281895450 suggest that backticks, among others, may not work well with cross-references as they may contain a code of a different language than D. Still, pretty recent PRs suggest that backticks should be used, but only for single words: - https://github.com/dlang/phobos/pull/5801 - https://github.com/dlang/phobos/pull/5970 I thought of updating the wiki to match the apparent consensus in this regard but wanted to make sure if it's really the way to go.
Jan 31 2018
On Wed, Jan 31, 2018 at 03:40:04PM +0000, Jakub Łabaj via Digitalmars-d wrote:What is the current state of the art of writing inline code in the documentation? Wiki says "use `...` instead of $(D ...)": https://wiki.dlang.org/Contributing_to_Phobos#Documentation_style. Some arguments made here: https://github.com/dlang/phobos/pull/5183#issuecomment-281895450 suggest that backticks, among others, may not work well with cross-references as they may contain a code of a different language than D. Still, pretty recent PRs suggest that backticks should be used, but only for single words: - https://github.com/dlang/phobos/pull/5801 - https://github.com/dlang/phobos/pull/5970 I thought of updating the wiki to match the apparent consensus in this regard but wanted to make sure if it's really the way to go.AFAIK, backticks is preferred because $(D ...) syntax is noisier, and harder to read in the source code. But otherwise, the two are equivalent. (In fact, backticks translate directly into $(D ...) in the ddoc code. They are just syntactic sugar.) But if your code snippet is longer than a line, you should use inline code block syntax: /** blah blah discussion here ---- /* code here */ void main() { ... } ---- blah blah discussion here */ T -- In a world without fences, who needs Windows and Gates? -- Christian Surchi
Jan 31 2018
On Wednesday, 31 January 2018 at 17:14:56 UTC, H. S. Teoh wrote:But otherwise, the two are equivalent. (In fact, backticks translate directly into $(D ...) in the ddoc code. They are just syntactic sugar.)No, they aren't. The `` is different in several ways including doing character escaping that macros are incapable of, and it expands to BACKTICK, not D. Read the comment of mine linked by the OP. They are intended to be separate, but you are right that the lighter syntax is getting more attention, much to my chagrin.
Jan 31 2018
On Wed, Jan 31, 2018 at 06:31:34PM +0000, Adam D. Ruppe via Digitalmars-d wrote:On Wednesday, 31 January 2018 at 17:14:56 UTC, H. S. Teoh wrote:Ah, then I stand corrected.But otherwise, the two are equivalent. (In fact, backticks translate directly into $(D ...) in the ddoc code. They are just syntactic sugar.)No, they aren't. The `` is different in several ways including doing character escaping that macros are incapable of, and it expands to BACKTICK, not D. Read the comment of mine linked by the OP.They are intended to be separate, but you are right that the lighter syntax is getting more attention, much to my chagrin.Coming from you, I'm a little surprised. Weren't you one of the people complaining that ddoc macro syntax is ugly? I actually share that sentiment, and have been avoiding using any explicit macro markup in my ddoc comments until `` came along that didn't make the source code (IMO) unreadable. Even now, I still refuse to use anything more than that in my own code, at least not directly (I did do one or two ddoc template customizations, but would not insert that into my source code itself). Though of course, when contributing to Phobos I just have to follow whatever other Phobos code does. (Still, I try to avoid touching ddoc macro syntax where possible. It makes me feel like I have to wash my hands afterwards.) T -- One reason that few people are aware there are programs running the internet is that they never crash in any significant way: the free software underlying the internet is reliable to the point of invisibility. -- Glyn Moody, from the article "Giving it all away"
Jan 31 2018
On Wednesday, 31 January 2018 at 21:34:47 UTC, H. S. Teoh wrote:Coming from you, I'm a little surprised. Weren't you one of the people complaining that ddoc macro syntax is ugly?$(H1 Rebuttal) It depends how you use it. For large blocks or for small, special bits, it doesn't bother me. So if I wanted to $(I point out) something in the middle, it doesn't bug me. $(QUOTE Similarly, if I want to call out a whole block of text, ddoc has some nice bits, like how easily it nests and can be added around existing text without thinking about it. ) $(H1 But...) $(P Where it starts to bug me is when you are using it $(I all over the place), especially with $(B random nesting).) $(P It is obnoxious to write on every paragraph, for example.) $(TABLE $(TR $(TD $(P or trying to make a table out of it) $(P especially if it is randomly formatted in the source. $(BR) $(B yikes!))))) Phobos does a lot of that latter filth, and almost never even tries to format it, making it even worse. My adrdox tries to eliminate most of the latter stuff Phobos uses, but it retains the ddoc syntax for the stuff I don't mind. In fact, I kinda $(B prefer) it to the *markdown way* in some places, since at least the ddoc is deliberate. Only thing that bugs me is when I try to write :) or 1) or similar in there but I plan to fix that. Now though, inline code like $(D) and $(REF) are ambiguous. They are short enough that they'd normally fall into my "ok with it" zone like $(B)... but they are also so common and I want to encourage their use. And having three shifted characters that must appear in order is kinda painful to type - it just breaks up the thought process, and can get somewhat weird to look at. So like I probably wouldn't write "The $(REF SimpleWindow) class is used along with the $(REF EventLoop) to create a window." without actually thinking about it, but "The [SimpleWindow] class is used with [EventLoop]" is almost thoughtless to type. The latter may be slightly easier to read.... but I think the bigger difference is just the friction in typing it the first time in this case. Emphasis ought to be rare anyway, but interlinking ought to be very common. I'm very very skeptical of claims of "it is faster to type" being significant... but easier to type I do think makes it more likely to be used. Most macros I think ought not be used frequently but this is different. BTW adrdox does [reference] instead of `reference` linking because of what I said before: `code` is too generic. It isn't necessarily a link. Moreover, my [reference|also allows alternative text to display], which wouldn't work well in ``.
Jan 31 2018
On Wed, Jan 31, 2018 at 10:55:38PM +0000, Adam D. Ruppe via Digitalmars-d wrote:On Wednesday, 31 January 2018 at 21:34:47 UTC, H. S. Teoh wrote:Then I guess we differ on this point. While I think the ddoc macro system, *as a macro system*, is pretty elegant in and of itself, I personally can't stand mixing it in with ddoc comments, which I've grown accustomed to be plain ole text, like other code comments. Interpreted differently by the compiler, sure. But having a different syntax? I find it too jarring and distracting. [...]Coming from you, I'm a little surprised. Weren't you one of the people complaining that ddoc macro syntax is ugly?$(H1 Rebuttal) It depends how you use it. For large blocks or for small, special bits, it doesn't bother me. So if I wanted to $(I point out) something in the middle, it doesn't bug me.$(P Where it starts to bug me is when you are using it $(I all over the place), especially with $(B random nesting).) $(P It is obnoxious to write on every paragraph, for example.) $(TABLE $(TR $(TD $(P or trying to make a table out of it) $(P especially if it is randomly formatted in the source. $(BR) $(B yikes!)))))Urgh, as if $(I this syntax) isn't already jarring enough, inserting what is basically a poor man's transliteration of HTML into ddoc syntax into source code is just ... it makes me wanna reach for the 'mark-block-delete' key combo in Vim. In general, almost all text macro / formatting systems, from LaTeX to HTML to ddoc, are universally ugly and verbose when it comes to tables, and makes my eyes bleed. The only exception I've found so far is markdown, where you can actually write this: |Blah|Blah| |----|----| |abc |def | |ghi |jkl | It's not perfect, but it's worlds better than the line noise syntax of the alternatives. [...]My adrdox tries to eliminate most of the latter stuff Phobos uses, but it retains the ddoc syntax for the stuff I don't mind. In fact, I kinda $(B prefer) it to the *markdown way* in some places, since at least the ddoc is deliberate. Only thing that bugs me is when I try to write :) or 1) or similar in there but I plan to fix that.Yeah, I'm not really a fan of *...* or _..._ in markdown syntax. It's just too easy to mix them up / misidentify them for identifiers in code or expressions, esp. if C-like pointer dereference syntax is used. Though I suppose that's what `...` is for. But then again, I rarely find the need to have emphasis in technical docs, so it's not a biggie. And I do still prefer *...* over $(B ...). I just don't like alphabetical macro names interspersed with text; it makes it hard to parse the text with the eye.Now though, inline code like $(D) and $(REF) are ambiguous. They are short enough that they'd normally fall into my "ok with it" zone like $(B)... but they are also so common and I want to encourage their use. And having three shifted characters that must appear in order is kinda painful to type - it just breaks up the thought process, and can get somewhat weird to look at. So like I probably wouldn't write "The $(REF SimpleWindow) class is used along with the $(REF EventLoop) to create a window." without actually thinking about it, but "The [SimpleWindow] class is used with [EventLoop]" is almost thoughtless to type.This is why I prefer markdown-style syntax.The latter may be slightly easier to read.... but I think the bigger difference is just the friction in typing it the first time in this case. Emphasis ought to be rare anyway, but interlinking ought to be very common. I'm very very skeptical of claims of "it is faster to type" being significant... but easier to type I do think makes it more likely to be used. Most macros I think ought not be used frequently but this is different.Actually, for me it's not so much a matter of "it's faster to type"; it's more of an issue of "when I'm reading (and presumably thinking (hard) about) source code, do I really want to expend the mental resources to parse the syntax of yet another embedded DSL inside a *comment*?". If I had my way, I would just write a normal comment as opposed to a doc comment. What makes the doc proposition attractive is that, in an ideal world, a "normal" comment can be automatically translated into nice docs without needing to pepper-spray it with foreign syntax particles, so that I can read the comment while working on the code, in addition to having nice docs to show to others in a format they prefer, like HTML or whatever. That's why I would actually welcome markdown-like syntax in ddoc. Yeah, it has limitations and sux in many ways, but IMNSHO you shouldn't be reimplementing complex HTML syntax inside a doc comment anyway -- leave that to an external templating engine or whatever you wish to use, and just let the doc comment be as readable as possible *as source code*.BTW adrdox does [reference] instead of `reference` linking because of what I said before: `code` is too generic. It isn't necessarily a link. Moreover, my [reference|also allows alternative text to display], which wouldn't work well in ``.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. 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 Let the templating engine or whatever identify the link for me and produce whatever HTML spew is necessary to make it work in a browser, just leave my source code alone already! T -- Shin: (n.) A device for finding furniture in the dark.
Jan 31 2018
FYI I am changing the subject line with this post since it is branching off the original question of simple best practices of code in ddoc. On Thursday, 1 February 2018 at 00:19:53 UTC, H. S. Teoh wrote:In general, almost all text macro / formatting systems, from LaTeX to HTML to ddoc, are universally ugly and verbose when it comes to tables, and makes my eyes bleed. The only exception I've found so far is markdown, where you can actually write this: |Blah|Blah| |----|----| |abc |def | |ghi |jkl | It's not perfect, but it's worlds better than the line noise syntax of the alternatives.So adrdox actually supports that (though you must label it), but I actually kinda hate it because it is enormously difficult to edit. Earlier today, in a work call, the non-programmers on the team asked me to define "beautiful code". I have two main criteria: 1) does it work? 2) is it easy to edit while keeping it working? When people say "code is read far more than it is written", I usually disagree: the main reason I read code is when I have to edit it! If it is working fine, it disappears into the background. But when there's a bug, I read it... as a means to the end of fixing the bug, which means editing it. So, technically, sure I'll agree it is read more than it is written, but code is rarely actually written just once. It needs to get edited for bug fixes, new features, and changing external requirements. How does that relate here? Take your ASCII table above and fix a misspelled word in the upper left cell. If you wrote "mispelled" instead of "misspelled", you just need to add the missing 's'.... and then go back and add spaces and/or dashes on each and every row to line the '|' column back up. In CS terms, it turned a constant-time edit into a O(n) operation, scaling linearly with the number of rows. But it isn't even the number of rows in the table, it is the number of rows in the source text, which can really explode when you need to elaborate in the table somehow: +-----------------------+ | This header | This | | needed three | does | | rows to fit. | not. | +==============+========+ | Here's some | More! | | text. | | +--------------+--------+ Let's add another word. +-----------------------+ | This header | This | | needed three | does | | more rows to | not. | | fit. | | +==============+========+ | Here's some | More! | | text. | | +--------------+--------+ Adding a 5-character word there took me *29* edit operations, not counting navigation of the caret. Now, maybe you use some editor macros to clean it up instead of doing it manually, but I don't have those... and if you need a fancy editor macro to just add a word to a comment, I think the comment syntax has failed. And how do you add a code sample inside the table? Oh I don't even want to try that. And let me emphasize this: this is comment in source code. If you want to read it as an end user, you can render it to HTML or whatever. In the source code, if you are reading it there... again, it is probably because you are editing it! 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? So, that syntax is nice for little tables that get trivial edits, but for larger info tables, I prefer writing it out as paragraphs some how. That's why adrdox also supports "table_rows" and "table_columns", which I borrowed from Python's restructured text. It is basically a vertical list - similar to Markdown's nested list syntaxes - of rows and columns, or columns and rows. See more of my stuff here: http://dpldocs.info/experimental-docs/adrdox.syntax.html#tables I don't love it all, but for the most part, I implement it because it is useful to me and I at least don't hate it (or because I was forced to for Phobos compatibility lol). So my above thing becomes: * + This header needed three more rows to fit. + This does not * - Here's some text. - More! So each * introduces a new row (or column, these must be bracketed to tell which style it is), then + introduces a table header, and - introduces a table cell. Alignment is trivial now, since it is just leading indentation (and that's optional, but to be fair, actually aligning the pipes is optional in Markdown's tables too, but if you don't it gets ugly anyway in both cases). Adding a new word there? Constant time operation again. Adding a code sample is simple too, you can write it vertically like any other. And it isn't quite as beautiful as the ASCII table for some cases... but it is still very legible in plain text source view, while being infinitely easier to edit. BTW this is my big justification for bracketed syntax: putting $(SMALL_TABLE) or $(TABLE_ROWS) or $(LIST) around those bullets tells the parser not only that you are intentionally opting into special syntax, but also tells it exactly how to interpret it. So we can reuse these simple bullet-point lists in the source for a couple different render modes.Yeah, I'm not really a fan of *...* or _..._ in markdown syntax. It's just too easy to mix them up / misidentify them for identifiers in code or expressions, esp. if C-like pointer dereference syntax is used. Though I suppose that's what `...` is for.Yes, the `...` stuff handles that, but is also just bugs me because when I write something like *foo* I actually DO intend for it to be rendered as *foo*, not as bold foo. For example, I like to text my friends "*hugs*". It kills me when that gets bolded. (yes, i know i can write \*hugs\* but barf.) Granted, I'm not frequently writing *hugs* in technical documentation, but the principle bugs me. Every time something like Facebook bolds my hugs it makes me hate markdown a little bit more.If I had my way, I would just write a normal comment as opposed to a doc comment.Ironically, ddoc was supposed to be that. https://dlang.org/spec/ddoc.html [quote] D's goals for embedded documentation are: It looks good as embedded documentation, not just after it is extracted and processed. 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. [/quote] 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 */ 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.yeah me too. Though ddox for a while syntax highlighted them too. And adrdox did too for a while, with $(D) though not `` since D is explicitly D language (though phobos authors frequently used it for non-D...) though I changed my mind on it after using it - it just distracted from the text instead of adding to it.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/blahadrdox 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. /** See also: [otherFunction] */ void foo() {} /** See also: [foo] */ void otherFunction() {} It knows those are local symbols so it looks them up in scope. adrdox understands D's import rules and even handles nested names. Having to get a URL there is a big hassle... what if a library gets a new fork/maintainer and the doc url changes? What if you want to render it offline? What a pain!
Jan 31 2018
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!)It tells quite a bit about the complexity of Ddoc that I had to add support for -D to run.dlang.io ...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.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/7043Using [...] 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/blahadrdox 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.
Jan 31 2018
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/75Z55oUhh, 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
Feb 01 2018
On Thursday, 1 February 2018 at 14:51:41 UTC, ag0aep6g wrote:On 02/01/2018 07:18 AM, Seb wrote: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!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/75Z55oUhh, 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
Feb 02 2018
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/75Z55oWell, 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.
Feb 01 2018
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: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.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.[...] 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
Feb 01 2018
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.
Feb 02 2018
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| --------------------
Feb 01 2018
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.
Feb 02 2018
On Friday, 2 February 2018 at 15:04:42 UTC, Adam D. Ruppe wrote:What bugs me with that sample is that the headers are repeated a lot... but it isn't bad.Yeah, the moment I scrolled the table header out of sight I can't make sense of the cells anymore.But re* sounds like maybe restructuredText which I borrowed some ideas from too.Ah, found, it's called recfile https://www.gnu.org/software/recutils/
Feb 03 2018
On 1/31/18 5:55 PM, Adam D. Ruppe wrote:Now though, inline code like $(D) and $(REF) are ambiguous. They are short enough that they'd normally fall into my "ok with it" zone like $(B)... but they are also so common and I want to encourage their use. And having three shifted characters that must appear in order is kinda painful to type - it just breaks up the thought process, and can get somewhat weird to look at.Where it breaks down is when you have many nested tags, and you end with ))))) I hate that. I've seen many bugs in the D documentation because of that. I'd rather we use different delimeters for different tags, like markdown. -Steve
Jan 31 2018
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
Jan 31 2018
On Wednesday, January 31, 2018 18:58:29 Walter Bright via Digitalmars-d wrote:On 1/31/2018 5:37 PM, Steven Schveighoffer wrote: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 DavisWhere 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
Jan 31 2018
On 1/31/18 9:58 PM, Walter Bright wrote:On 1/31/2018 5:37 PM, Steven Schveighoffer wrote: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. -SteveWhere 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.
Feb 01 2018
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: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!On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.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.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.
Feb 01 2018
On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:On 1/31/18 9:58 PM, Walter Bright wrote:The #if too?On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.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.When I'm reviewing a PR, I don't see the matching as easily.True, but that applies to anything with a block structure.
Feb 02 2018
On 2/2/18 7:10 PM, Walter Bright wrote:On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:Yes. http://vim.wikia.com/wiki/Moving_to_matching_bracesOn 1/31/18 9:58 PM, Walter Bright wrote:The #if too?On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.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.Sure, I also have a difficult time with loads of parentheses in function calls too. I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line. Note: if there are brace issues, the auto-tester fails it. Why did that example I posted not catch the extra closing paren? Can we have it do so? -SteveWhen I'm reviewing a PR, I don't see the matching as easily.True, but that applies to anything with a block structure.
Feb 04 2018
On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-PNote: if there are brace issues, the auto-tester fails it. Why did that example I posted not catch the extra closing paren? Can we have it do so?[...] Ddoc does complain about it, though it seems it's not treated as a compile error. It's probably just a matter of making the autotester parse the compiler output to look for these error/warning messages, and forcing a test failure if found. T -- Without geometry, life would be pointless. -- VS
Feb 04 2018
On Monday, 5 February 2018 at 06:27:02 UTC, H. S. Teoh wrote:On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]Yeah DMD emits those warnings and until recently -w with warnings didn't even result in DMD terminating with a non-zero exit code, though we finally fixed that a few weeks ago and 2.079 will finally behave as expected: https://github.com/dlang/dmd/pull/7440 Also note that you can't check-in any code in the core repositories with failing Ddoc messages. This was checked for Phobos for a long time, while again for DMD and druntime that was only added recently, e.g.: https://github.com/dlang/dmd/pull/7432I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-PNote: if there are brace issues, the auto-tester fails it. Why did that example I posted not catch the extra closing paren? Can we have it do so?[...] Ddoc does complain about it, though it seems it's not treated as a compile error. It's probably just a matter of making the autotester parse the compiler output to look for these error/warning messages, and forcing a test failure if found.
Feb 04 2018
On 2/5/18 1:27 AM, H. S. Teoh wrote:On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful. -SteveI don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-P
Feb 05 2018
On Mon, Feb 05, 2018 at 09:50:38AM -0500, Steven Schveighoffer via Digitalmars-d wrote:On 2/5/18 1:27 AM, H. S. Teoh wrote:[...] Apparently it's a prevailing style for Lisp and Lisp dialects like Scheme. Random example (this is in Guile, a Scheme dialect, quoted from open source code): (define (match-predicate obj alist) (if (null? alist) "Unknown type" (if (apply (caar alist) obj) (cdar alist) (match-predicate obj (cdr alist))))) The only way I can keep my sanity while editing this sort of code is vim's jump-to-match feature. T -- "If you're arguing, you're losing." -- Mike ThomasOn Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-P
Feb 05 2018
On Monday, 5 February 2018 at 15:27:56 UTC, H. S. Teoh wrote:On Mon, Feb 05, 2018 at 09:50:38AM -0500, Steven Schveighoffer via Digitalmars-d wrote:It's common in Scheme/Racket to use square brackets for nested terms: (let ([x (random 4)] [o (random 4)]) (cond [(> x o) "X wins"] [(> o x) "O wins"] [else "cat's game"])) I find code written like your example (which is unfortunately quite common) to be no different from poorly-written Perl code. Properly indented and square bracketed Scheme code is easy to read. One of the nice things about D IMO is that you have to work harder to write ugly code. Atrocities like chaining a bunch of function calls together don't look bad in D.On 2/5/18 1:27 AM, H. S. Teoh wrote:[...] Apparently it's a prevailing style for Lisp and Lisp dialects like Scheme. Random example (this is in Guile, a Scheme dialect, quoted from open source code): (define (match-predicate obj alist) (if (null? alist) "Unknown type" (if (apply (caar alist) obj) (cdar alist) (match-predicate obj (cdr alist))))) The only way I can keep my sanity while editing this sort of code is vim's jump-to-match feature. TOn Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-P
Feb 05 2018
On 05.02.2018 16:27, H. S. Teoh wrote:Apparently it's a prevailing style for Lisp and Lisp dialects like Scheme. Random example (this is in Guile, a Scheme dialect, quoted from open source code): (define (match-predicate obj alist) (if (null? alist) "Unknown type" (if (apply (caar alist) obj) (cdar alist) (match-predicate obj (cdr alist))))) The only way I can keep my sanity while editing this sort of code is vim's jump-to-match feature.I additionally use: https://www.emacswiki.org/emacs/RainbowDelimiters
Feb 05 2018
On Monday, 5 February 2018 at 14:50:38 UTC, Steven Schveighoffer wrote:On 2/5/18 1:27 AM, H. S. Teoh wrote:When I programmed AutoLISP extension in AutoCAD I would use parentheses in the exact same way as I use { } in C. So not at the end of a line but vertically at the level of indentation; (defun xy (car (cdr (cons a b) ) ) ) This made it much better to handle.On Sun, Feb 04, 2018 at 02:34:31PM -0500, Steven Schveighoffer via Digitalmars-d wrote: [...]I still have nightmares from my scheme class in college... Literally the professor would be up at the whiteboard scribbling a scheme function, and at the end, he would draw a whole bunch of closing parentheses in a row, reciting the opening parentheses for each one "car, cdr, ..." I also have seen people's code who DID put all their closing braces on one line. It was... awful.I don't have a hard time with braces. It tends to be worse with parentheses. Generally these are indented properly, and not }}}}} all on one line.Wait till you see Lisp code. :-P
Feb 05 2018
On Mon, Feb 05, 2018 at 06:38:22PM +0000, Patrick Schluter via Digitalmars-d wrote: [...]When I programmed AutoLISP extension in AutoCAD I would use parentheses in the exact same way as I use { } in C. So not at the end of a line but vertically at the level of indentation; (defun xy (car (cdr (cons a b) ) ) ) This made it much better to handle.That's also my personal preference. Unfortunately, such practice is frowned upon by some Scheme communities. Why, is absolutely beyond me. :-D T -- LINUX = Lousy Interface for Nefarious Unix Xenophobes.
Feb 05 2018
On 2/4/2018 11:34 AM, Steven Schveighoffer wrote:On 2/2/18 7:10 PM, Walter Bright wrote:So I see. I wonder when that was added to vim. I put it in MicroEmacs in the late 1980s, and vi definitely didn't have it then. I didn't put in Pascal begin/end, because I didn't care for Pascal :-)On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:Yes. http://vim.wikia.com/wiki/Moving_to_matching_bracesOn 1/31/18 9:58 PM, Walter Bright wrote:The #if too?On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.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.
Feb 04 2018
On 2/5/18 2:53 AM, Walter Bright wrote:On 2/4/2018 11:34 AM, Steven Schveighoffer wrote:I should clarify -- the matching parentheses feature has been in vim forever (note -- vim didn't exist in the last 80s, straight vi I think doesn't have these features). I don't know how long the matching #if/#endif feature has been there, I haven't used it much. A nice feature of this is that the "jump to match" command is like any other move command in vim -- you can hook it to copy/pasting, deleting, formatting, etc. It's very useful. But this is a bit off topic :) -SteveOn 2/2/18 7:10 PM, Walter Bright wrote:So I see. I wonder when that was added to vim. I put it in MicroEmacs in the late 1980s, and vi definitely didn't have it then. I didn't put in Pascal begin/end, because I didn't care for Pascal :-)On 2/1/2018 6:09 AM, Steven Schveighoffer wrote:Yes. http://vim.wikia.com/wiki/Moving_to_matching_bracesOn 1/31/18 9:58 PM, Walter Bright wrote:The #if too?On 1/31/2018 5:37 PM, Steven Schveighoffer wrote:This has literally been in vim since I started using it, what, 15 years ago? It doesn't matter.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.
Feb 05 2018
On Wednesday, January 31, 2018 16:19:53 H. S. Teoh via Digitalmars-d wrote:In general, almost all text macro / formatting systems, from LaTeX to HTML to ddoc, are universally ugly and verbose when it comes to tables, and makes my eyes bleed. The only exception I've found so far is markdown, where you can actually write this: |Blah|Blah| |----|----| |abc |def | |ghi |jkl | It's not perfect, but it's worlds better than the line noise syntax of the alternatives.Yeah. Tables are generally ugly, though they're also not super-common in documentation - perhaps enough to be annoying, but most functions don't have them.Actually, for me it's not so much a matter of "it's faster to type"; it's more of an issue of "when I'm reading (and presumably thinking (hard) about) source code, do I really want to expend the mental resources to parse the syntax of yet another embedded DSL inside a *comment*?". If I had my way, I would just write a normal comment as opposed to a doc comment. What makes the doc proposition attractive is that, in an ideal world, a "normal" comment can be automatically translated into nice docs without needing to pepper-spray it with foreign syntax particles, so that I can read the comment while working on the code, in addition to having nice docs to show to others in a format they prefer, like HTML or whatever. That's why I would actually welcome markdown-like syntax in ddoc. Yeah, it has limitations and sux in many ways, but IMNSHO you shouldn't be reimplementing complex HTML syntax inside a doc comment anyway -- leave that to an external templating engine or whatever you wish to use, and just let the doc comment be as readable as possible *as source code*.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. 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. Ddoc is by no means perfect, but I don't see adding magical syntax as being a particular nice fix. Clearly, there's some disagreement on that front however. Personally, I actually like the fact that the website is done in ddoc, and while sometimes it looks ugly in the documentation, it mostly looks just fine. 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. To get it right, the compiler would have to actually act like a documentation generator and not just like it's compiling a file to ddoc. - Jonathan M Davis
Jan 31 2018
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.
Feb 02 2018
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 DavisI 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 DavisIMHO, 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.
Feb 02 2018
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:[...] 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 Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M DavisI 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.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.
Feb 02 2018
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 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!)
Feb 02 2018
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:[...] 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. [...]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...[...] 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.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!)
Feb 02 2018
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.
Feb 02 2018
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'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)b905180b1fffa78f922677ee90ed8ae9b803fc4f
Feb 02 2018
On Saturday, 3 February 2018 at 04:37:44 UTC, Adam D. Ruppe wrote:On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:I think that would only work if we drop the ddoc of phobos entirely or add a similar feature to ddoc. Don't get me wrong, I like adrdox a lot more than ddoc and I don't like the REF Ddoc feature either.This is the kind of thing you should be promoting to Andrei to convince him that dpldocs is better. ;-)I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)b905180b1fffa78f922677ee90ed8ae9b803fc4f
Feb 03 2018
On Saturday, 3 February 2018 at 11:41:27 UTC, Seb wrote:I think that would only work if we drop the ddoc of phobos entirely or add a similar feature to ddoc.I could live with either :P But the underscore thing is just plain bad. Literally NOBODY has ever liked it - every time this comes up, people are not happy with it saying "why is my word randomly italicized" and "why do i have to put _ randomly in phobos". Just even such an OBVIOUS GLARING FLAW with a reasonably straightforward replacement path (define the highlight macro to be a no-op, minimally, or just simply remove the "feature" entirely with a transition switch to warn you every time it sees what is now an extra _ on a word - that's what I did with adrdox and fixed my Phobos fork up in about 30 mins) hits a brick wall.Don't get me wrong, I like adrdox a lot more than ddoc and I don't like the REF Ddoc feature either.BTW I am going to have another burst of time to do improvements to it soon, and I think I still have a list of nits from you so you might see some nice improvements in the coming month. February is a somewhat slow month for me with day job work which means I expect to be able to afford a good block of time to work on this again.
Feb 03 2018
On Saturday, 3 February 2018 at 04:37:44 UTC, Adam D. Ruppe wrote:On Friday, 2 February 2018 at 20:15:11 UTC, H. S. Teoh wrote:Have you thought of simply postprocessing REF_ALTTEXT for your documentation engine for now? That won't lead to merge conflicts ;-) e.g. sed -i "s/[$](REF_ALTTEXT \([^,]*\),\([^,]*\),[^)]*)/[\2|\1]" **/*.dThis is the kind of thing you should be promoting to Andrei to convince him that dpldocs is better. ;-)I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)b905180b1fffa78f922677ee90ed8ae9b803fc4f
Feb 03 2018
On Saturday, 3 February 2018 at 11:44:44 UTC, Seb wrote:Have you thought of simply postprocessing REF_ALTTEXT for your documentation engine for now?It actually supports the macro, so I could just keep the upstream source here, just the difference between them is kinda striking. The history here is there were a lot of broken links in the phobos source because they used LINK2 when I forked. I changed them to my [reference] syntax and made the point that if it is broken for me, it is broken for ddox too, so a macro should be introduced to fix it. After that, the $(REF) and $(REF_ALTTEXT) macros were introduced in Phobos.... but I had already changed all the LINK2 in my tree to my syntax, so when Phobos changed their LINK2s to REF later (it took between months and years for Phobos to catch up to what I was able to accomplish in days and weeks!), I added support for the Phobos macro too, but the ones I had already changed the syntax on caused these merge conflicts. I pasted it here just because of the kinda striking difference. And adrdox actually even supports pseudo-symbol references of this type so you could just write [input-range] and it'd look it up from a user-supplied glossary (located in the source of package.d btw, it is scoped just like a real symbol) to know the term and the appropriate link! But even the long form you see above is just so much nicer than the macro one. You don't have to tell the compiler something the compiler already knows - which import isInputRange comes from.
Feb 03 2018
On Sat, Feb 03, 2018 at 04:37:44AM +0000, Adam D. Ruppe via Digitalmars-d wrote: [...]I'm updating my fork now and check out this merge conflict: <<<<<<< HEAD * source = The [isInputRange|input range] to encode. ======= * source = The $(REF_ALTTEXT input range, isInputRange, std,range,primitives) * to _encode.+1000. That misfeature has been continually plaguing us ever since it was introduced, leading to a constant endless churn of PRs sprinkling _'s everywhere just to suppress ddoc's "helpful" highlighting of stuff it shouldn't have highlighted in the first place. Extremely annoying. T -- A linguistics professor was lecturing to his class one day. "In English," he said, "A double negative forms a positive. In some languages, though, such as Russian, a double negative is still a negative. However, there is no language wherein a double positive can form a negative." A voice from the back of the room piped up, "Yeah, yeah."My syntax is so much prettier. (note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)b905180b1fffa78f922677ee90ed8ae9b803fc4f
Feb 03 2018
On Sat, Feb 03, 2018 at 06:18:55AM -0800, H. S. Teoh via Digitalmars-d wrote:On Sat, Feb 03, 2018 at 04:37:44AM +0000, Adam D. Ruppe via Digitalmars-d wrote: [...][...] I got sick of just whining about, and decided to do something about it instead: https://github.com/dlang/dmd/pull/7834 Destroy! T -- Right now I'm having amnesia and deja vu at the same time. I think I've forgotten this before.(note that the stupid leading _ is something I strip out too. Ddoc's most moronic "feature". Can we PLEASE kill that?!?!?!!)+1000. That misfeature has been continually plaguing us ever since it was introduced, leading to a constant endless churn of PRs sprinkling _'s everywhere just to suppress ddoc's "helpful" highlighting of stuff it shouldn't have highlighted in the first place. Extremely annoying.
Feb 03 2018
On Saturday, 3 February 2018 at 17:20:35 UTC, H. S. Teoh wrote:I got sick of just whining about, and decided to do something about it instead:Whelp, g'luck. I've tried to null out the macro before, maybe this approach will work better. The stupid thing should just be killed entirely though. It was never of any legitimate value.
Feb 03 2018
On Sat, Feb 03, 2018 at 06:25:26PM +0000, Adam D. Ruppe via Digitalmars-d wrote:On Saturday, 3 February 2018 at 17:20:35 UTC, H. S. Teoh wrote:This approach is more likely to be accepted. ;-)I got sick of just whining about, and decided to do something about it instead:Whelp, g'luck. I've tried to null out the macro before, maybe this approach will work better.The stupid thing should just be killed entirely though. It was never of any legitimate value.Shh! The plan is, after this PR gets merged, it becomes easier to turn off the behaviour by default as part of a PR to improve the default ddoc stylesheet. Once it's off by default, we can delete the code as "dead code". ;-P T -- The easy way is the wrong way, and the hard way is the stupid way. Pick one.
Feb 03 2018
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.
Jan 31 2018
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:It's: $(REF lowerCase, std,string) or $(REF_ALTTEXT alternative text, lowerCase, std,string)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.
Feb 01 2018
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.
Feb 01 2018