Re: Improving ddoc
On Tuesday, 6 January 2015 at 15:31:52 UTC, Adam D. Ruppe wrote: could debate the specific contents of it, h1 works for me but i kinda think h1 should be the outer aggregate name and then h2 if it is a nested member... but regardless, ddoc doesn't let you change the macros based on nesting anyway, but it does have the concept of grouped sections with headers. Well, either way, if ddoc is worth fixing it would be a good idea to stick to HTML5 spec since they eventually managed to clean up the header mess of HTML4 (somewhat). http://www.w3.org/TR/html5/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements
Re: Improving ddoc
On Tuesday, 6 January 2015 at 15:17:32 UTC, Ola Fosheim Grøstad wrote: The "header" element belongs in a sectioning element Right, DDOC_SECTION is a and the first element of it that ddoc outputs is is a DDOC_SECTION_H - a section header. We could debate the specific contents of it, h1 works for me but i kinda think h1 should be the outer aggregate name and then h2 if it is a nested member... but regardless, ddoc doesn't let you change the macros based on nesting anyway, but it does have the concept of grouped sections with headers.
Re: Improving ddoc
On Tuesday, 6 January 2015 at 15:13:00 UTC, Adam D. Ruppe wrote: But if these macros were better, it could be a $0 where the x is the right level. The "header" element belongs in a sectioning element and the first heading in each section should be "h1": ... ...
Re: Improving ddoc
On Tuesday, 6 January 2015 at 15:00:06 UTC, Dicebot wrote: Wait what? It isn't formatted as as far as I can see. How exactly this is supposed to work? That makes a DDOC_SECTION. The default macro is DDOC_SECTION_H = $(B $0)$(BR) DDOC_SECTION = $0$(BR)$(BR) But if these macros were better, it could be a $0 where the x is the right level. I might spend a day revamping these macros eventually, the default ones are so bad, they make poor html and hide some of ddoc's own features.
Re: Improving ddoc
On Thursday, 1 January 2015 at 21:52:59 UTC, Walter Bright wrote: On 1/1/2015 7:09 AM, Dicebot wrote: headers 3. === headers: Wait what? It isn't formatted as as far as I can see. How exactly this is supposed to work?
Re: Improving ddoc
On 1/2/2015 4:29 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: Now, full credit to the rust community: they were immediately friendly and helpful in advising me how to deal with this (you can pass a flag to the ./configure command to request not to build the docs). And of course you can see this as primarily a fault in how the build system defines its targets and their dependencies. But the simple fact is, had documentation generation been built in rather than relying on 3rd-party tools, it would never have been an issue, _and_ I'd have ended up having the documentation as well as just the compiler executable and libraries. Note that Doxygen is a third party tool, it also requires a bunch more third party tools. A friend of mine bemoaned using a piece of software on Linux that required not one but multiple different and specific versions of Perl be installed in order to even build the software. Back in the early days of my compiler business, Microsoft shipped a linker on the DOS disks. So all my users had a linker. Unfortunately, the linker versions changed constantly. Eventually MS left the linker off of the DOS disks, but would include it on the disks of all sorts of other software they sold. The result was I couldn't rely on users having a linker, or any particular linker. There was a blizzard of MS linkers in the wild, each with their own features and bugs. It was a support nightmare, consuming more and more of my time. I had disks filled with my "linker collection" to test against. Finally, I got my own linker (written by Bjorn Freeman-Benson). It wasn't the greatest linker evar, but it worked, it was consistent, I knew what users had, and I could fix bugs in it rather than find workarounds. I learned over and over that controlling the full stack of what the user needed was very practical.
Re: Improving ddoc
On 2015-01-02 15:12, Mathias LANG wrote: I don't see it being useful for Phobos, or any other library. Have one doc with the public API available, optionally another one for the framework/lib devs (but those often prefers the code). I see that being useful for any open source library. I don't mind having an option to enable/disable generating documentation for private symbols. Strongly agree for the constraints. For __FILE__ & __LINE__, what would it affects ? I can think of exception-related stuff, anything else ? A perfect example where this is a big issue is the upcoming std.logger [1]. It looks absolutely horrible. Every logging functions has five of these arguments and in 99.99% of the cases you do not need to pass these arguments manually. [1] http://burner.github.io/phobos/phobos-prerelease/std_logger_core.html -- /Jacob Carlborg
Re: Improving ddoc
On 03/01/15 01:11, Walter Bright via Digitalmars-d wrote: An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a rather simple piece of code. Very much so, and your point elsewhere in this thread about how valuable it is to have a built-in documentation tool is absolutely spot-on. A story to illustrate this ... A few days ago I had a go at building and installing the rust compiler (no, I'm not jumping ship, I just decided it was about time I started getting some proper hands-on understanding of some of the alternative design approaches out there:-). This uses pandoc to generate documentation, which in turn evokes pdflatex, xelatex or lualatex, with the last of these being the preferred option. One ./configure && make later, and after quite a bit of compilation, the compiler itself was built -- at which point, the makefile tried to go on and build the documentation, and failed, for reasons I still don't understand (it was the lualatex command that was failing, but the error message was not very clear in conveying what the actual problem was). OK, well, the compiler is built, right? So let's try 'make install' ... oh no, the first thing it tries to do is to complete the 'make all' target and build the docs, and of course that fails, so it doesn't install anything. :-\ Now, full credit to the rust community: they were immediately friendly and helpful in advising me how to deal with this (you can pass a flag to the ./configure command to request not to build the docs). And of course you can see this as primarily a fault in how the build system defines its targets and their dependencies. But the simple fact is, had documentation generation been built in rather than relying on 3rd-party tools, it would never have been an issue, _and_ I'd have ended up having the documentation as well as just the compiler executable and libraries.
Re: Improving ddoc
On 1/2/2015 1:23 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I can live with you not addressing my irritation :-) But since we're discussing how to improve Ddoc, I thought it best to make sure that my issues with it were well described and understood. I like to think I do understand the issue :-) even if I don't agree with many conclusions. An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a rather simple piece of code.
Re: Improving ddoc
On 1/2/2015 1:42 PM, Adam D. Ruppe wrote: On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote: I agree. Excessive use of bold is like shouting at people - it's wearying to read. Pull any programming book off the shelf and flip through it. There's very little use of bold. Aye, my opinion now is that `code` is the only really important one. I can live without the others. List, table, and link might be nice, but totally non-essential in my eyes; plain ASCII or recursive macros look good enough to me. I agree. I was telling Andrei last night what a good idea you'd had.
Re: Improving ddoc
Joseph Rushton Wakeling via Digitalmars-d wrote: > Three things I'm not sure about: (i) does it allow definitions of custom > macros as with Ddoc (although I'm not sure how necessary that is in > practice); (ii) I have a nasty feeling its @keyword markup syntax (e.g. > @return @param etc.) might not play nice with D code examples; (iii) I > suspect we'd have to do some integration work getting D support into > Doxygen in order to enjoy the best of all its features. AFAIK @keyword is javadoc style (but supported by doxygen) and original doxygen style uses \keyword.
Re: Improving ddoc
On 02/01/15 22:40, Adam D. Ruppe via Digitalmars-d wrote: On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: Er, I believe I posted an example of just that :-) error stray paren :) Uh oh, another one! It actually is kinda a pity to me that it is such a common character. /** You know the worst thing? I can't use emoticons in my ddoc ;-) This makes me very sad, and I can't even express my sadness without generating another warning. :-( Although I can, speaking tongue in cheek, see how some people might consider that a bonus. :-P */ Imagine if macros were: ¤“name ‗ argument ‗ arg2”! But I don't suppose we can ask people to map hotkeys to conveniently write the docs either :( Seriously: how feasible could it be to address the issue by delineating the start and end of macros by a _pair_ of characters, reducing the chance of ambiguity? $(NEW_MACRO this would be the new macro system)$
Re: Improving ddoc
On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote: I agree. Excessive use of bold is like shouting at people - it's wearying to read. Pull any programming book off the shelf and flip through it. There's very little use of bold. Aye, my opinion now is that `code` is the only really important one. I can live without the others. List, table, and link might be nice, but totally non-essential in my eyes; plain ASCII or recursive macros look good enough to me.
Re: Improving ddoc
On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: Er, I believe I posted an example of just that :-) error stray paren :) Uh oh, another one! It actually is kinda a pity to me that it is such a common character. In my macro expander I wrote for css uses this weird character: ¤ to start a macro. That way, I could be reasonably sure it would never show up anywhere else, simplifying the code a bit. By mapping it to F7 in my editor, it is easily available despite not being on the keyboard, and it is even in the 8-bit character set my old fonts use, so it would show up there too. Imagine if macros were: ¤“name ‗ argument ‗ arg2”! But I don't suppose we can ask people to map hotkeys to conveniently write the docs either :(
Re: Improving ddoc
On 1/2/2015 1:06 AM, Andrei Alexandrescu wrote: Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of bold in dlang.org should actually be code. -- Andrei I agree. Excessive use of bold is like shouting at people - it's wearying to read. Pull any programming book off the shelf and flip through it. There's very little use of bold.
Re: Improving ddoc
On 02/01/15 10:34, Andrei Alexandrescu via Digitalmars-d wrote: On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. I don't think that's fair. AFAICS the only reason there's a "Stray ')'" issue to be concerned about is because the ) character is used to mark the end of a Ddoc macro. OK, I accept that it's rare that you get a ) without it being preceded by an opening ). But there are surely much rarer (in code) characters that could have been used, or the end-of-macro marker could have been chosen to be something completely unambiguous like $) or )$.
Re: Improving ddoc
On 02/01/15 22:03, Walter Bright via Digitalmars-d wrote: The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it). Er, I believe I posted an example of just that :-) I'm entirely open to the possibility of reworking the 'uniform' function so that its bounds are indicated in a different way, but it _is_ something that currently occurs in D code (albeit not frequently). Grep the Phobos sources, the only stray paren issue in it is the use of [..) in a few places in the documentation. I know it's irritating for you, but it simply is not prevalent. I can live with you not addressing my irritation :-) But since we're discussing how to improve Ddoc, I thought it best to make sure that my issues with it were well described and understood.
Re: Improving ddoc
On Friday, 2 January 2015 at 21:03:44 UTC, Walter Bright wrote: On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote: On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it). Not that I know of. [ and ] are for function application/calls in mathematica and ( ) have their normal order-of-evaluation meaning.
Re: Improving ddoc
On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote: On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it). Grep the Phobos sources, the only stray paren issue in it is the use of [..) in a few places in the documentation. I know it's irritating for you, but it simply is not prevalent.
Re: Improving ddoc
On Thursday, 1 January 2015 at 20:15:55 UTC, Walter Bright wrote: A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not On the contrary, the complaint is that you can create your own macros and loose the semantics of the markup. I looked at the possibility to create a high quality javascript based front end to phobos documentation last year and the messy macro-markup/generated html killed the project before it got started. Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ LaTeX is not a standard. It is a quick'n'dirty macro-hack over TeX. If you want to mark up math, use HTML5's MathML and use MathJax for browsers that don't fully support it. http://www.w3.org/Math/ http://www.mathjax.org/sponsors/
Re: Improving ddoc
On Friday, 2 January 2015 at 09:40:45 UTC, Andrei Alexandrescu wrote: * Automatically generating cross-references Nice. https://github.com/rejectedsoftware/ddox/blob/master/README.md#ddox-documentation-engine I'm still wondering why it's not shipped with DMD. * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? Agree. It would break one of the goal of Ddoc (It does not repeat information that the compiler already knows from parsing the code.) Note that ddox also do that http://vibed.org/api/vibe.core.concurrency/ . It's not perfect, but you're sure it's always up to date, and is way more readable than what Phobos is currently doing with BOOKTABLE. * Documentation for private symbols should be generated but hidden by default in the output with a button to show them Nice. I don't see it being useful for Phobos, or any other library. Have one doc with the public API available, optionally another one for the framework/lib devs (but those often prefers the code). * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default Nice. Strongly agree for the constraints. For __FILE__ & __LINE__, what would it affects ? I can think of exception-related stuff, anything else ? Also, I was very puzzled with $(D) when I was looking for the right way to use it. I think the answer is relevent to this dicussion: https://github.com/rejectedsoftware/vibe.d/pull/875 Most of the issues, IMO, are stylistic. We should firstly work on improving the output, rather than introduce new syntax. Also, documentation is much more subjective than code (just like success and adult content :o) ). We could introduce control flags to ensure some minima are met, examples that come to mind are: --ddoc-werror (build failure on doc warning), --ddoc-require=params,returns (require Params and Returns sections to be defined, those can be empty for trivial functions), --ddoc-document=public (require every public symbols to be documented).
Re: Improving ddoc
On Wednesday, 31 December 2014 at 19:50:49 UTC, Andrei Alexandrescu wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! Quite often pull requests for the changelog [0] contain unbalanced parens. Maybe we can replace some of the parens with indent level nesting? Example: $(BUGSTITLE Language Changes, $(LI $(RELATIVE_LINK2 asm-attributes, Asm statements can now be used in pure nothrow @nogc @trusted code.)) ) $BUGSTITLE Language Changes $LI $RELATIVE_LINK2 asm-attributes, Asm statements can now be used in pure nothrow @nogc @trusted code. An indented block is the last argument to a macro (BUGSTITLE). A macro without parens has all of it's arguments on the same line. Commas belong to the innermost macro (RELATIVE_LINK2). Parens can still be used. [0]: https://github.com/D-Programming-Language/dlang.org/blob/master/changelog.dd
Re: Improving ddoc
On 1/1/15 4:39 AM, Walter Bright wrote: On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote: On 12/31/14 1:12 PM, Dicebot wrote: I don't feel like any small change in DDOC will make me like/use it. I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately. " and ` naturally come in pairs, but *, _ and ' do not. What about #[{( anything inside here can use markdown )}]# I'm half joking about the brackets, but some method of saying "in here, I permit markdown" would make this both backwards compatible, and not inflict too much damage to readability of ddoc. In fact, if you did something like: /**[[ ... comments with markdown ]]*/ or something like this at the beginning of each ddoc comment, it would be almost unnoticeable. I'd also suggest giving a toggling mechanism, something like: /** $(MARKDOWN true/false) **/ Which allows one to set the default for the enclosed ddocs. That's my contribution to the project :) I wish I could actually code it... -Steve
Re: Improving ddoc
On 1/1/15 4:46 AM, ketmar via Digitalmars-d wrote: On Thu, 01 Jan 2015 01:30:58 -0800 Andrei Alexandrescu via Digitalmars-d wrote: On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote: sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa. It would be awesome indeed if the civil atmosphere in this forum would be restored. I very much hope in your help with this. -- Andrei i'm trying to do my best. honestly! ;-) i'm deleting first two or three variants of many replies. so my answers looks perfectly calm for me... until i see them posted. yet i'll try to improve than situation in this year. maybe deleting first ten variants, i don't know... ;-) This is a frequent habit of mine, I always re-read my posts until I feel comfortable that I wouldn't mind reading it (most of the time, it takes at least 2 reviews). Anything especially antagonistic usually gets extra scrutiny :) If NNTP posted replies as I typed them, I would be banned for sure... -Steve
Re: Improving ddoc
On 2015-01-02 10:40, Andrei Alexandrescu wrote: * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? No, why would we do that? I want be able to easily generate good documentation. If something requires an extra step to make it better it will not be as easy. I also think it will be easier for Ddoc to do this than doing it in a postprocess step: * Ddoc will already have all the information available * The postprocessing tool will need to parse the output to get this information * If Ddoc is supposed to be designed for multiple output formats the postprocessing tool need to be able to handle that as well. Also, it should be possible to disable this if it's not desired. * A nice tree view with all packages and modules with filter for all symbols This seems like a matter of styling, not functionality. I don't see how this can be a matter of styling if it should support filtering. I'm thinking of something like the Scala documentation I linked to [1]. It has something more like a flat list with different sections. It doesn't matter if you call it styling of functionality ;) I still would like to see it in the default output. [1] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg
Re: Improving ddoc
On Thursday, 1 January 2015 at 22:38:05 UTC, Jacob Carlborg wrote: That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable To me Ddoc documentation is different from javadoc-flavored documentation and rightfully so. Ddoc is module centered with some nice introduction at the top and includes helpful unittest examples, too. Where OO-centered reference documentation puts comments to all classes and methods, Ddoc allows (and encourages) documentation that can be read to learn about the module. You know, I am your average troll, spending my time reading documentation. Pure reference documents are no fun to read.
Re: Improving ddoc
On 2015-01-02 10:10, Andrei Alexandrescu wrote: On 1/1/15 7:01 AM, Ary Borenszweig wrote: 1. Add "* foo" syntax for lists Currently ddoc ignores leading * so we'd need another character if at all. A dash. -- /Jacob Carlborg
Re: Improving ddoc
On 2015-01-02 02:31, ketmar via Digitalmars-d wrote: i think that in most cases you can use `r"..."` instead. and if you really want backticks, you can use dedicated code block for that. One really good use case for backticks is when the string contains double quotes. -- /Jacob Carlborg
Re: Improving ddoc
On 1/1/15 2:38 PM, Jacob Carlborg wrote: On 2014-12-31 20:50, Andrei Alexandrescu wrote: In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that. Sounds great, thanks. I think the solution is to use Ddoc as it is today, with full support for Github flavored Markdown added and a couple of other enhancements. Full support would probably break a lot of extant documentation. The reason is listed below: I'm not going to argue so much about the syntax since many others have already done so. The functionality that I feel is missing: * Automatically generating cross-references Nice. * Inhering documentation. Methods that override some other method should automatically inherit the documentation of the overridden method, unless there's already documentation present for that method or explicitly disable the inheritance with a command. Nice! * A list of summary with all symbols should be automatically generated for a module Shouldn't we leave that to postprocessing? * Documentation for private symbols should be generated but hidden by default in the output with a button to show them Nice. * A nice tree view with all packages and modules with filter for all symbols This seems like a matter of styling, not functionality. * Automatically create links to the source code for each symbol. This could either be to syntax highlighted source code Ddoc generates or to Github. There could be a flag (or some other way) to specify which Github project to link to Nice. * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default Nice. The following should automatically be generated for a given class: * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable Looks like a great list, thanks. Andrei
Re: Improving ddoc
On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote: I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei
Re: Improving ddoc
On 1/1/15 6:26 AM, Adam D. Ruppe wrote: Honestly, I think _foo_ and /foo/ are both not worth supporting in this context. *bold* is the only one we really need - the most common, and the least ambiguous. Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of bold in dlang.org should actually be code. -- Andrei
Re: Improving ddoc
On 1/1/15 7:01 AM, Ary Borenszweig wrote: 1. Add "* foo" syntax for lists Currently ddoc ignores leading * so we'd need another character if at all. 2. Add **bold** and __bold__ How necessary are these? 3. Add *italic* and _italic_ Maybe these would be more often useful. 4. Make `some text` automatically link to other D code. For example `std.algorithm.any` would automatically link to http://dlang.org/phobos/std_algorithm.html#.any . This must work for types, functions, etc. If it doesn't resolve to a symbol, just put it inside ... Nice. 5. Make [text](url) denote a link. Nice. 6. Remove macros. We probably can't do that. Thanks! Andrei
Re: Improving ddoc
On 1/1/15 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote: Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN) which would be better coded as: $(INTERVAL x .. y) INTERVAL=[$0$(RPAREN) See, this is my point. $(INTERVAL x .. y) is, to my mind, less clear to read _in the source_ than [x, y). If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-) "Serious flaw" sounds like a serious exaggeration. The notation "[x, y)" has unpaired parens. Any tool relying on pairing parens is going to have difficulty with it. This is exactly the kind of argument that diminishes the value of an otherwise great notion - that ddoc needs improvements addressing pain points with it. Andrei
Re: Improving ddoc
On Thu, 01 Jan 2015 21:51:06 +0100 Jacob Carlborg via Digitalmars-d wrote: > On 2015-01-01 16:09, Dicebot wrote: > > My top list of md shortcuts for "casual" documentation: > > > > 1. `code` > > > > 2. * lists > > > > headers > > 3. === > > I prefer the hashtag syntax: > > # header > > ## header there is nothing wrong in supporting both. ;-) signature.asc Description: PGP signature
Re: Improving ddoc
On Thu, 01 Jan 2015 11:57:37 -0800 Walter Bright via Digitalmars-d wrote: > Is also hard to read. Yes, I'm being facetious, but take a look at those > examples posted here about how ugly Ddoc is - they're of that category. and you know why? 'cause nobody cares to make 'em human readable, as it's almost impossible with Ddoc. so why someone should waste his time on that? on contrary, human-readable markup tend to be formatted to be actually human-readable. yet i will not argue anymore, as you seem to ignore the fact that most people don't want to do DTP in API documentation. this is very easy to judge: just preapprove markdown-like parser for documentation (without throwing off Ddoc) and then see what people will use most of the time. i bet you know the answer. signature.asc Description: PGP signature
Re: Improving ddoc
On Thu, 01 Jan 2015 15:40:30 +0100 Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote: > > Again those are: *bold* and `code`. > > I would be inclined to prefer ``code`` or ```code```, simply because it's > valid > D syntax to have, > > auto someString = `Some great big string`; > i think that in most cases you can use `r"..."` instead. and if you really want backticks, you can use dedicated code block for that. signature.asc Description: PGP signature
Re: Improving ddoc
On 2 January 2015 at 05:42, Walter Bright via Digitalmars-d wrote: > On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote: >> >> I was thinking more along the lines of letting doxygen inspire >> enhancements to ddoc, since as far as I can see, it's pretty much the >> standard these days, and people already know it. > > > And others are saying "Markdown is the standard." It is, doxygen supports markdown. Doxygen users are generally familiar with markdown in docs. > BTW, Boost doesn't seem to use Doxygen, apparently because it crashes > reading Boost C++ files: > > http://stackoverflow.com/questions/3349783/boost-doxygen-documentation Hah. C++ is such a pig, I'm amazed it's actually POSSIBLE to parse it anymore! ;)
Re: Improving ddoc
On 2 January 2015 at 03:06, Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 17:16, Manu via Digitalmars-d wrote: >> >> Doxygen supports both @param and \param. > > > Ah yes, I'd forgotten that. It's been a while :-\ > >> It would be really good if doxygen supported D comprehensively. I >> often port C code to D which already has doxygen commentary. I never >> port the doxygen docs to ddoc though. > > > Did you ever try preserving the docs and continuing to use doxygen to > generate them? If so, how did it go? Or is that an outright impossibility? Doxygen doesn't know about most D-specific concepts stuff. Other language concepts are usually a subset of C/C++, but C++ is really a subset of D. Doxygen needs some new concepts as far as I can tell.
Re: Improving ddoc
On 2014-12-31 20:50, Andrei Alexandrescu wrote: In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that. I think the solution is to use Ddoc as it is today, with full support for Github flavored Markdown added and a couple of other enhancements. The reason is listed below: I'm not going to argue so much about the syntax since many others have already done so. The functionality that I feel is missing: * Automatically generating cross-references * Inhering documentation. Methods that override some other method should automatically inherit the documentation of the overridden method, unless there's already documentation present for that method or explicitly disable the inheritance with a command. * A list of summary with all symbols should be automatically generated for a module * Documentation for private symbols should be generated but hidden by default in the output with a button to show them * A nice tree view with all packages and modules with filter for all symbols * Automatically create links to the source code for each symbol. This could either be to syntax highlighted source code Ddoc generates or to Github. There could be a flag (or some other way) to specify which Github project to link to * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default The following should automatically be generated for a given class: * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg
Re: Improving ddoc
On 01/01/15 21:15, Walter Bright via Digitalmars-d wrote: My point is there's ALWAYS going to be some sort of escaping mechanism, and it is ALWAYS going to interfere with the look of anyone who wants to use the full character set on the keyboard, which IS going to happen whenever you write math text. Yes, I accept that. I'm just pointing out what I find problematic with this particular escaping mechanism, given the documentation needs of the code I'm involved with. I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. Before I reply to the rest of your email, I think I should point out two things: * I understand that ddoc is a macro system, I understand what that means and how flexible and powerful it can be (I've used LaTeX for years, and I have created my own custom ddoc macros). I'm not trying to persuade you to give that up. * I'm not trying to advocate for you to start supporting markdown, although I do understand why some people are. * LaTeX maths notation on the other hand ... ;-) - actually I'm mostly raising this last point to tease you, but there is a serious side; I'll explain later in the email. Anyway, to some details ... You don't have to call it INTERVAL. You can write your own macro to name it whatever works for you. I do it all the time. You can even then change the definition of the macro and, for example, have it styled differently (like use a different font, different font weight, different color, etc.) I find that very handy. Yes, I understand that I can write different macros to mean different things. But surely you can understand my point from the previous email, that having 4 different macros to indicate the different types of intervals, is much less nice from a reading/writing point of view than just being able to write, in ASCII, [x, y], (x, y], [x, y) and (x, y). It's not just maths notation either -- this will trigger the 'Stray )' warning too: Example: auto u = uniform!"[)"(0.0, 1.0); I think we can achieve that simplicity of reading, not just for these two examples, but for potentially quite a bit more maths and code, without sacrificing any of the things you're interested in keeping. A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not realizing that C code can contain custom written functions. Here's one example that was brought up in the discussion: https://github.com/D-Programming-Language/phobos/pull/2828 A custom macro made all the difference. Not only that, it is now easy to switch it from a table to a definition list, or have custom styling for it, all without messing anything else up. This cannot be done with Markdown. You might ask "why would we want custom styling"? Turns out that that example is a nice one for why not use it. Yes, and nothing I say here should be taken as denying the usefulness or desirability of being able to do that. BTW talking of custom macros and custom styling, that file has something I consider to be a horrendous violation of good styling design in it: MYREF = href="#.$1">$1 Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ Sure, but even with unicode, there's a limit to how sanely you can represent a complex formula in plain-text. Personally, this is the point where I'd rather be able to use inline LaTeX formulas, because I think most people interested in complex formulas will be able to understand that. Please don't dismiss this idea out of hand: I think there are some handy tools we could use to integrate this very well into our documentation system. Using the MathJax javascript makes it pretty easy to embed LaTeX formulas into an HTML document: http://www.mathjax.org/ ... and obviously when outputting to LaTeX, it becomes much easier to just hand on LaTeX formulas as they are. If we could do something like, $(MATH F(x) = \int_{0}^{10} f(x) dx ) then it would be very nice. Obviously this won't work notationally quite as-is, but I don't see why it shouldn't be possible to find something similar that is workable. (N.B. this is a definite "Dream Wishlist" item, so please don't see it as the main concern of my email; if it isn't workable, just tell me that and move on to the end of the email, where there is the point I really would like your feedback on.) Isn't * a super common math character? and |? and +? All of which are markdown characters. Well, as I'm not arguing for markdown, this may be a moot point. But I don't recall encountering those issues
Re: Improving ddoc
On 1/1/2015 7:09 AM, Dicebot wrote: headers 3. === headers:
Re: Improving ddoc
On 2014-12-31 20:50, Andrei Alexandrescu wrote: One simple starter would be to allow one escape character, e.g. the backtick (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write `MACRO arg1, arg2`. I don't see how that would improve anything, at all. -- /Jacob Carlborg
Re: Improving ddoc
On 2015-01-01 16:09, Dicebot wrote: My top list of md shortcuts for "casual" documentation: 1. `code` 2. * lists headers 3. === I prefer the hashtag syntax: # header ## header -- /Jacob Carlborg
Re: Improving ddoc
On 2015-01-01 01:44, Rikki Cattermole wrote: The AST stuff would guaranteed be a DIP (second to last CTFE implementation type, well as I define it anyway). http://wiki.dlang.org/DIP50 ;) -- /Jacob Carlborg
Re: Improving ddoc
On 2015-01-01 14:28, Andrej Mitrovic via Digitalmars-d wrote: The wxWidgets developers maintain a hand-written set of doxygen interface files because doxygen actually crashes when trying to parse the C++ code directly. As a result the documentation is frequently out of date. I remember filing numerous patches to fix their docs (over 100 of them), it was blatantly out of date[1]. We would have the same problem with D. Any time there were syntax changes in D we would have to fix doxygen to be able to parse D code again. I'm pretty sure I read on the Clang mailing list that someone wants to use Clang to extract doxygen comments. -- /Jacob Carlborg
Re: Improving ddoc
On 2015-01-01 01:21, Rikki Cattermole wrote: Following this, we could extend this one altogether. AST entry points. Read only (later maybe not) full access to dmd-fe AST. So we're back at AST macros :). I don't mind but I don't think it's the right solution in this case. -- /Jacob Carlborg
Re: Improving ddoc
On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote: It's just noisy and hard to read, as I think we've established to be the popular opinion. Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. At this point it might be helpful to point out that Ddoc does its jobs very well. It deserves praise on its merits. For properly documented code, however, it requires more visual noise than desirable. Take std/algorithm.d as an example. In my opinion replacing $(D ...) with `...` boosts the file considerably. The beauty of markdown is that it requires significantly less visual noise. It is not clean what markdown actually is, so voting for it might be nonsensical. On the other hand, I believe in reading source code and some documentation in phobos is unreadable to me. This is why I think Ddoc should be improved.
Re: Improving ddoc
On 1/1/2015 12:02 PM, Andrej Mitrovic via Digitalmars-d wrote: Well the actual truth is that doxygen is pretty much the C++ standard, while Markdown is a standard for everything else. :) My experience with C/C++ is that no documentation is the standard :-)
Re: Improving ddoc
On 1/1/2015 12:04 PM, Adam D. Ruppe wrote: On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library. I know. But have you ever seen badly formatted C code? Do you conclude from that that C code is inherently ugly? Or do you say "hey, fix the formatting!" Why the hell were they written that way in the first place? Beats the crap out of me, but they ARE written that way... Yep, and I've seen a lot of crappily formatted D code, too. That's pretty much died down in the Phobos submissions, because the reviewers won't allow it in. Little comparable attention, however, has been paid to the Ddoc style. I did put to rights one of the posted examples: https://github.com/D-Programming-Language/phobos/pull/2828
Re: Improving ddoc
On 1/1/2015 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: See, this is my point. $(INTERVAL x .. y) is, to my mind, less clear to read _in the source_ than [x, y). My point is there's ALWAYS going to be some sort of escaping mechanism, and it is ALWAYS going to interfere with the look of anyone who wants to use the full character set on the keyboard, which IS going to happen whenever you write math text. If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? You don't have to call it INTERVAL. You can write your own macro to name it whatever works for you. I do it all the time. You can even then change the definition of the macro and, for example, have it styled differently (like use a different font, different font weight, different color, etc.) I find that very handy. A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not realizing that C code can contain custom written functions. Here's one example that was brought up in the discussion: https://github.com/D-Programming-Language/phobos/pull/2828 A custom macro made all the difference. Not only that, it is now easy to switch it from a table to a definition list, or have custom styling for it, all without messing anything else up. This cannot be done with Markdown. You might ask "why would we want custom styling"? Turns out that that example is a nice one for why not use it. I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-) Isn't * a super common math character? and |? and +? All of which are markdown characters. The only time the stray paren issue comes up is in the interval notation.
Re: Improving ddoc
On Thursday, 1 January 2015 at 20:00:12 UTC, Ola Fosheim Grøstad wrote: Because it is true? :-) Documents are old fashion, what you want is an interactive frontend to an information database. One thing I would like to do is add $(TAGS sorting, searching) etc to functions where applicable which can be linked to auto-generated lists and it can do categorization tables, etc. I did a proof of concept of this years ago but there wasn't much interest at the time. (Arguably, now we could just group tagged functions into a submodule instead...)
Re: Improving ddoc
On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig wrote: I really don't understand why you say that. Because it is true? :-) Documents are old fashion, what you want is an interactive frontend to an information database. I would suggest D to use a simple language to write the documentation, and then a powerful tool that understands the You sometimes need to add annotations to enhance what can be deduced. That is obvious for dynamic languages (so you have JSDoc, which is kinda like JavaDoc/Doxygen), but it also holds for languages with static typing.
Re: Improving ddoc
On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote: Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library. Why the hell were they written that way in the first place? Beats the crap out of me, but they ARE written that way...
Re: Improving ddoc
On 1/1/15, Walter Bright via Digitalmars-d wrote: > On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote: >> I was thinking more along the lines of letting doxygen inspire >> enhancements to ddoc, since as far as I can see, it's pretty much the >> standard these days, and people already know it. > > And others are saying "Markdown is the standard." Well the actual truth is that doxygen is pretty much the C++ standard, while Markdown is a standard for everything else. :)
Re: Improving ddoc
On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote: It's just noisy and hard to read, as I think we've established to be the popular opinion. I'm sure we can also agree that: #include\ #include\ int main\ (){print\ f("hello\ world\n\ ");retur\ n EXIT_S\ UCCESS;} Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category. Consider also this Ddoc code: / This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***/ And lastly, people initially hated the D template syntax: foo!(args) foo!arg but today it elicits nary a ripple - it's liked now. It's simply familiar now.
Re: Improving ddoc
On 01/01/15 20:42, Walter Bright via Digitalmars-d wrote: On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote: I was thinking more along the lines of letting doxygen inspire enhancements to ddoc, since as far as I can see, it's pretty much the standard these days, and people already know it. And others are saying "Markdown is the standard." I think the two are not in contradiction, because as Manu noted earlier in the thread, Doxygen now permits Markdown to be used in its documentation.
Re: Improving ddoc
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote: I was thinking more along the lines of letting doxygen inspire enhancements to ddoc, since as far as I can see, it's pretty much the standard these days, and people already know it. And others are saying "Markdown is the standard." BTW, Boost doesn't seem to use Doxygen, apparently because it crashes reading Boost C++ files: http://stackoverflow.com/questions/3349783/boost-doxygen-documentation
Re: Improving ddoc
On Thursday, 1 January 2015 at 18:24:47 UTC, JN wrote: I should be able to click SysTime and go to that type definition. Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/) vibe.d docs are generated using custom tool by Sonke, ddox, not the stock DDOC. Among other things it does automatically search for cross-references when generating the docs, no additional markup required afair.
Re: Improving ddoc
On 1/1/15 3:32 AM, Walter Bright wrote: On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote: Stars and underlines are popular due to markdown. There'd be limitations, e.g. pairs occurring across a ddoc parent won't be considered for expansion etc. Also the defaults can be written to be idempotent. (Below I am removing the single quote because indeed it's not fitting): BACKQUOTED=`$0` QUOTED="$0" UNDERLINED=_$0_ STARRED=*$0* So essentially we get to start 100% backward compatible and figure out under what circumstances the macros expand. I think we can get this working. Ddoc assumes ( ) nests. But this would require that these characters nest, too: *abc_def * _i for example, which is stretching things a bit because they do not naturally nest. No nesting. Again I'm talking simple rules. They should get us a ton of mileage. -- Andrei
Re: Improving ddoc
On 1/1/15 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-( You're not but that's really rare. uniform01 is a rare case of unpaired paren in code. -- Andrei
Re: Improving ddoc
On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig wrote: and I can't believe that after 10+ years of development, D documentation still doesn't have a basic feature like inter-linking between types (I even once submitted a PR but it wasn't accepted because other code was written on top of it and then the merge was hard to do). For example: http://dlang.org/phobos/std_file.html#.timeLastModified I should be able to click SysTime and go to that type definition. Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/)
Re: Improving ddoc
On 1/1/15 2:35 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= " wrote: On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote: What's cross-library-indexing? You mean show documentation for many libraries at once? Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format. I really don't understand why you say that. I just started writing a documentation generator for the Crystal programming language. http://crystal-lang.org/api/ You can read about its features here: http://crystal-lang.org/2014/12/31/crystal-0.5.6-release.html Now, I go here http://dlang.org/phobos/std_file.html and I can't believe that after 10+ years of development, D documentation still doesn't have a basic feature like inter-linking between types (I even once submitted a PR but it wasn't accepted because other code was written on top of it and then the merge was hard to do). For example: http://dlang.org/phobos/std_file.html#.timeLastModified I should be able to click SysTime and go to that type definition. But, DDoc can generate Latex. Then, take a look at Rust. Guess what they use for their documentation? Markdown! Here's a web framework called Iron: http://ironframework.io/ Here are the API docs: http://ironframework.io/doc/iron/ Let's take a look at enum.Method: http://ironframework.io/doc/iron/method/enum.Method.html See that red "String" text? Click it and it takes you here: http://doc.rust-lang.org/nightly/collections/string/struct.String.html Wow! It took you to the String definition in an entirely different host! Back to Crystal's docs, below every method there's a "View Source" link that takes you to that code in GitHub. No such thing in D. Note that all of this was done with just Markdown (HTML) and by making the documentation generator understand and use the language as much as possible, something with DDoc doesn't do. I once submitted a PR to fix that, but it was ignored. I would suggest D to use a simple language to write the documentation, and then a powerful tool that understands the semantics of the language and allows you to generate good looking, easily browsable documentation. Neither JSON, XML, YAML or macros are needed for that.
Re: Improving ddoc
On Thursday, 1 January 2015 at 14:37:31 UTC, Adam D. Ruppe wrote: On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote: I actually like DDoc as it is, and finds it readable. You know, if $(D_CODE) escaped the code properly and `code` was a shortcut to it... that'd actually solve my big complaints with the ddoc language itself and make it convenient. For a preview how this might look like: perl -p -e 's/\$\(D ([^\$()]*+(\((?:[^\$()]*+|(?1))*\))*[^\$()]*)\)/`$1`/g' std/algorithm.d | less
Re: Improving ddoc
On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote: What's cross-library-indexing? You mean show documentation for many libraries at once? Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format.
Re: Improving ddoc
On 1/1/15 1:23 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= " wrote: On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote: it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings. What's cross-library-indexing? You mean show documentation for many libraries at once?
Re: Improving ddoc
On Thu, Jan 01, 2015 at 01:19:06AM -0800, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/31/14 1:12 PM, Dicebot wrote: > >I don't feel like any small change in DDOC will make me like/use it. > > I'm envisioning quite an interesting possibility in which certain > constructs are automatically converted to macros: > > `hello world` --> $(BACKQUOTED hello world) > "hello world" --> $(QUOTED hello world) > 'hello world' --> $(SQUOTED hello world) > _hello world_ --> $(UNDERLINED hello world) > *hello world* --> $(STARRED hello world) > > ... and such. Then generating nice formatting for each of these > constructs is achieved by simply defining these macros appropriately. [...] Nice idea, but I think _..._ will have to be left out, due to the prevalence of special meanings of _ currently in use. For example, _abc currently means "abc" without any automatic highlighting (e.g., if abc were a parameter or function name); _abc: at the beginning of a line means a literal word "abc" where otherwise abc: would mean a section heading "abc"; and abc_def: means a section heading with two words "abc def". I anticipate that overloading _ to do even more than this will only lead to a nasty mess where it's impossible for the non-expert to figure out what it actually means. T -- The early bird gets the worm. Moral: ewww...
Re: Improving ddoc
On 01/01/15 17:16, Manu via Digitalmars-d wrote: Doxygen supports both @param and \param. Ah yes, I'd forgotten that. It's been a while :-\ It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though. Did you ever try preserving the docs and continuing to use doxygen to generate them? If so, how did it go? Or is that an outright impossibility?
Re: Improving ddoc
On 1 January 2015 at 21:51, Walter Bright via Digitalmars-d wrote: > On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote: >> >> Why is doxygen insufficient? Is there a reason ddoc was invented >> rather than supporting the practically-industry-standard doxygen >> format from the start? > > > There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 > or 3 people used it. > > The problem was Doxygen was some add on tool. It was not part of the > downloadable D package. It couldn't be. Anyone wanting to use Doxygen was > going to have to: > > 1. pray a version exists on the platform they have that D is installed on. > 2. pray that version was the one the D docs were expecting. > 3. buy Doxygen. > 4. download and install Doxygen successfully. > 5. Doxygen is a large and complex tool - lots of work to understand it. > 6. expect the D community to provide tech support with "Doxygen is not > working on my D documents." > > The end result was, essentially nobody used Doxygen. In fact, nobody used > any sort of documentation system, and we know what the result looked like - > your typical out-of-date, totally wrong, or non-existent normally found with > C and C++ projects. > > Ddoc, being: > > 1. always there > 2. always the correct version > 3. Ddoc is trivial to learn and use > > revolutionized the D documentation. And that's an understatement. I'm not arguing that it wasn't an excellent decision to include a doc parser in DMD, but I don't think any of those advantages are attributed to the ddoc syntax specifically so much as just including it in the compiler. I'm sure the ddoc syntax is fine. It's just noisy and hard to read, as I think we've established to be the popular opinion. I'm just suggesting that DMD could also parse some useful subset of doxygen as ddoc shorthand. I don't think parsing doxygen would be particularly difficult. Basically all the suggestions here so far, like the markdown bits are valid doxygen.
Re: Improving ddoc
On Thursday, 1 January 2015 at 15:09:22 UTC, Dicebot wrote: My top list of md shortcuts for "casual" documentation: 1. `code` https://github.com/D-Programming-Language/dmd/pull/4228 That's by far my #1 syntax-wise, and since my implementation uses the existing code, it will be relevant semantically too at some point - when the code examples get cross-referencing, inline bits will too, so we can link with that too (probably*). The others aren't even really important to me at all; $(HEADER foo) or Foo: both look good enough for me. Tables might be nice, but overall aren't that big of a deal to me. * A potential problem running it through that D highlighter is not all `code` is necessarily D code. But most of it is and the rest still seems to work well enough - my xml tag test passed - so I think it is the biggest win for ddoc.
Re: Improving ddoc
On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote: it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings.
Re: Improving ddoc
On Thursday, 1 January 2015 at 12:05:03 UTC, Walter Bright wrote: There is also nothing stopping anyone from using Doxygen if they prefer it. Sure, but there is a big advantage in having a the same tech doc format for all libraries for the same language/group of languages. I've spent way too much time learning new essential languages, so learning a new one for a fringe activity like writing tech docs is not going to happen. Picking a common subset of an existing markup language will reduce resistance to learning the one D is using. Doxygen syntax is a good candidate if you want people to write uniform docs for D libraries. Especially if D is going to continue to focus on C++ integration.
Re: Improving ddoc
On 1 January 2015 at 20:16, Andrei Alexandrescu via Digitalmars-d wrote: > On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: >> >> On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote: >>> >>> No particular system was clearly dominant when Walter invented ddoc. >>> Also I >>> might be frequenting the wrong circles; most people I know and myself >>> aren't >>> fluent at all with doxygen. -- Andrei >> >> >> It is really trivial to learn and quite effective. > > > Totally. I did use it briefly a few years ago and I'm sure I can relearn it. > > My point here was to give context for ddoc's history. FWIW switching dlang > and phobos now to doxygen would be a major effort and I'm not sure we'd be > in a better place even after assuming perfect execution. I was thinking more along the lines of letting doxygen inspire enhancements to ddoc, since as far as I can see, it's pretty much the standard these days, and people already know it.
Re: Improving ddoc
On 1 January 2015 at 20:02, Joseph Rushton Wakeling via Digitalmars-d wrote: > On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote: >> >> No particular system was clearly dominant when Walter invented ddoc. Also >> I >> might be frequenting the wrong circles; most people I know and myself >> aren't >> fluent at all with doxygen. -- Andrei > > > It is really trivial to learn and quite effective. I used it years ago for > a C/C++ project; when I encountered Ddoc my reaction was, "OK, it's > basically a custom and slightly weirder-looking variant of Doxygen..." > > It has some _very_ nice features such as the easy inclusion of LaTeX > formulas into documentation, and in my experience Doxygen markup is much > more readable-in-source than Ddoc. > > Three things I'm not sure about: (i) does it allow definitions of custom > macros as with Ddoc (although I'm not sure how necessary that is in > practice); (ii) I have a nasty feeling its @keyword markup syntax (e.g. > @return @param etc.) might not play nice with D code examples; (iii) I > suspect we'd have to do some integration work getting D support into Doxygen > in order to enjoy the best of all its features. Doxygen supports both @param and \param. It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though.
Re: Improving ddoc
On 1 January 2015 at 19:33, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote: >> >> On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d >> >> wrote: >>> >>> Hello, >>> >>> >>> In wake of the recent discussions on improving ddoc syntax we're looking >>> at >>> doing something about it. Please discuss any ideas you might have here. >>> Thanks! >>> >>> One simple starter would be to allow one escape character, e.g. the >>> backtick >>> (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one >>> can write `MACRO arg1, arg2`. >> >> >> I don't really have any particular opinions on this topic, but the >> only feeling I've really had in the past is, "why is it so different >> from doxygen?" >> Most people are already familiar with doxygen. >> >> Why is doxygen insufficient? Is there a reason ddoc was invented >> rather than supporting the practically-industry-standard doxygen >> format from the start? > > > No particular system was clearly dominant when Walter invented ddoc. Okay. > Also I might be frequenting the wrong circles; most people I know and myself > aren't > fluent at all with doxygen. -- Andrei What do you tend to use instead? I miss doxygen's '\' tags. For instance, '\a argName' to refer to a function argument argName, which will be formatted appropriately and all that. I find it a lot less visually distracting. It might also be interesting to note that doxygen implemented markdown support quite some time back, so I think there's precedent for people expecting that markdown be available for use in their documentation.
Re: Improving ddoc
On Thursday, 1 January 2015 at 15:21:40 UTC, ponce wrote: On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote: Again those are: *bold* and `code`. I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`; Github, Stack Overflow, trac and others use one single escape quote. And such snippet is much more likely to go into dedicated code block: ``` auto someString = `Some great big string`; ``` than as an inline snippet.
Re: Improving ddoc
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote: Again those are: *bold* and `code`. I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`; Github, Stack Overflow, trac and others use one single escape quote.
Re: Improving ddoc
My top list of md shortcuts for "casual" documentation: 1. `code` 2. * lists headers 3. === -- 4. | tables | that are | -- | pretty | in source | --
Re: Improving ddoc
On 12/31/14 4:50 PM, Andrei Alexandrescu wrote: Hello, In wake of the recent discussions on improving ddoc syntax we're looking at doing something about it. Please discuss any ideas you might have here. Thanks! One simple starter would be to allow one escape character, e.g. the backtick (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write `MACRO arg1, arg2`. Andrei 1. Add "* foo" syntax for lists 2. Add **bold** and __bold__ 3. Add *italic* and _italic_ 4. Make `some text` automatically link to other D code. For example `std.algorithm.any` would automatically link to http://dlang.org/phobos/std_algorithm.html#.any . This must work for types, functions, etc. If it doesn't resolve to a symbol, just put it inside ... 5. Make [text](url) denote a link. 6. Remove macros. Walter said: "Oh, Markdown can't be used to change the typography, generate TOCs, etc.?". Well, you don't need to do those things. Changing the typography will make it look ugly. You need a TOC? That's the job of the documentation tool (the binary), not the documentation syntax. Basically, use Markdown :-) Keep DDoc as it is now. Use it for your website if you want, to write books or whatever. But for documentation don't use it as it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. I repeat: keep DDoc, enhance it, use it as dog food for your websites, books, etc. Use something simpler and less powerful for documenting types and functions.
Re: Improving ddoc
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`; Eh, that breaks my habit from stack overflow. How often do you write an inline `raw string` anyway? It'd still just work inside ---\ncode\n--- blocks, and you could still do $(D_CODE auto s = `code`;) if you wanted to.
Re: Improving ddoc
On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote: Again those are: *bold* and `code`. I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`;
Re: Improving ddoc
On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote: I actually like DDoc as it is, and finds it readable. You know, if $(D_CODE) escaped the code properly and `code` was a shortcut to it... that'd actually solve my big complaints with the ddoc language itself and make it convenient. Really, those are the two things I want, I don't really care about the rest of the argument. Maybe it is PR time.
Re: Improving ddoc
On Thursday, 1 January 2015 at 11:33:25 UTC, Walter Bright wrote: Ddoc assumes ( ) nests. But this would require that these characters nest, too: *abc_def * _i for example, which is stretching things a bit because they do not naturally nest. I think someone who writes *long bold text like this* is in error anyway; I lose track of what those stars are supposed to me. (BTW the gmail html to text converter does this, making emails unreadable to me!) I would say the pattern to match would be \w\*[a-zA-Z0-9]+\*\w. Honestly, I think _foo_ and /foo/ are both not worth supporting in this context. *bold* is the only one we really need - the most common, and the least ambiguous. We do NOT want it to think *a = *b; is supposed to be bolding. We do NOT want it to think _object._method is supposed to be underlined. We do NOT want it to think /bin/bash is supposed to be italic. (Granted, those might be in code blocks anyway, but still, no point making this harder than it has to be.) But when would you write *a* = foo in code? Never, I don't think that's ever valid. So making that a $(STARRED) macro should just work in pretty much all circumstances. And we can always fall back on $(B bold) and $(I italic) when we do need them. I just think shooting for an 80% solution is more reasonable than a 99 or 100% solution - just do the easiest, least ambiguous shortcuts and use macros for the rest of them. It'll probably go a LONG way. Again those are: *bold* and `code`.
Re: Improving ddoc
On Thursday, 1 January 2015 at 14:16:05 UTC, Adam D. Ruppe wrote: On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. Yeah. The enormous irony is the #1 ddoc justification - and one of the big reasons doxygen or xml wasn't used IIRC - is 1. It looks good as embedded documentation, not just after it is extracted and processed. 2. It's easy and natural to write, i.e. minimal reliance on and other clumsy forms one would never see in a finished document. http://dlang.org/ddoc.html blargh :( I actually like DDoc as it is, and finds it readable. Markdown is readable and all but the specifications are just insane. http://commonmark.org/
Re: Improving ddoc
On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton Wakeling via Digitalmars-d wrote: My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. Yeah. The enormous irony is the #1 ddoc justification - and one of the big reasons doxygen or xml wasn't used IIRC - is 1. It looks good as embedded documentation, not just after it is extracted and processed. 2. It's easy and natural to write, i.e. minimal reliance on and other clumsy forms one would never see in a finished document. http://dlang.org/ddoc.html blargh :(
Re: Improving ddoc
On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote: Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN) which would be better coded as: $(INTERVAL x .. y) INTERVAL=[$0$(RPAREN) See, this is my point. $(INTERVAL x .. y) is, to my mind, less clear to read _in the source_ than [x, y). If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-)
Re: Improving ddoc
On Thursday, 1 January 2015 at 13:28:39 UTC, Andrej Mitrovic via Digitalmars-d wrote: Anyway, maybe we can do something about ddoc and make it easier to use. I'm just saying the grass isn't necessarily greener on the other side. +1. Every documentation tool has its problems. IMO, changing documentation system from the dedicated one would be a step backwards. Piotrek
Re: Improving ddoc
On 1/1/15, Andrei Alexandrescu via Digitalmars-d wrote: > Totally. I did use it briefly a few years ago and I'm sure I can relearn > it. The wxWidgets developers maintain a hand-written set of doxygen interface files because doxygen actually crashes when trying to parse the C++ code directly. As a result the documentation is frequently out of date. I remember filing numerous patches to fix their docs (over 100 of them), it was blatantly out of date[1]. We would have the same problem with D. Any time there were syntax changes in D we would have to fix doxygen to be able to parse D code again. Anyway, maybe we can do something about ddoc and make it easier to use. I'm just saying the grass isn't necessarily greener on the other side. [1]: http://trac.wxwidgets.org/search?ticket=on&q=drey&page=13&noquickjump=1
Re: Improving ddoc
On 1/1/2015 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-( Other than the: $(INTERVAL 0, 1) macro, you can use: &rparen; or the unicode ❳ which looks like a right ) : [0, 1❳ You can also use: [0, 1[ which is actually an international standard notation: http://en.wikipedia.org/wiki/ISO_31-11#Sets
Re: Improving ddoc
On 1/1/2015 2:21 AM, Andrei Alexandrescu wrote: Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The majority are in changelog.dd; I guess a couple of macros might help there. There are also things in the language spec documentation like: $(B $(LPAREN) $(RPAREN)) which are simply unnecessary. Instead: $(B ( ))
Re: Improving ddoc
On 1/1/2015 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: I ask because for me, one of the biggest annoyances of Ddoc (in terms of source readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc accidentally seeing a macro where there is none. Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN) which would be better coded as: $(INTERVAL x .. y) INTERVAL=[$0$(RPAREN)
Re: Improving ddoc
On 1/1/2015 3:09 AM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= " wrote: Adopting Doxygen would give you some benefits: "Doxygen is developed under Mac OS X and Linux, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available." -- http://www.stack.nl/~dimitri/doxygen/ There are no packages for FreeBSD, for example. Doxygen is GPL, but appears to be supported by only one person. There is also nothing stopping anyone from using Doxygen if they prefer it.
Re: Improving ddoc
On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote: Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start? There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 people used it. The problem was Doxygen was some add on tool. It was not part of the downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going to have to: 1. pray a version exists on the platform they have that D is installed on. 2. pray that version was the one the D docs were expecting. 3. buy Doxygen. 4. download and install Doxygen successfully. 5. Doxygen is a large and complex tool - lots of work to understand it. 6. expect the D community to provide tech support with "Doxygen is not working on my D documents." The end result was, essentially nobody used Doxygen. In fact, nobody used any sort of documentation system, and we know what the result looked like - your typical out-of-date, totally wrong, or non-existent normally found with C and C++ projects. Ddoc, being: 1. always there 2. always the correct version 3. Ddoc is trivial to learn and use revolutionized the D documentation. And that's an understatement.
Re: Improving ddoc
On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote: Stars and underlines are popular due to markdown. There'd be limitations, e.g. pairs occurring across a ddoc parent won't be considered for expansion etc. Also the defaults can be written to be idempotent. (Below I am removing the single quote because indeed it's not fitting): BACKQUOTED=`$0` QUOTED="$0" UNDERLINED=_$0_ STARRED=*$0* So essentially we get to start 100% backward compatible and figure out under what circumstances the macros expand. I think we can get this working. Ddoc assumes ( ) nests. But this would require that these characters nest, too: *abc_def * _i for example, which is stretching things a bit because they do not naturally nest.
Re: Improving ddoc
On Thursday, 1 January 2015 at 10:16:01 UTC, Andrei Alexandrescu wrote: My point here was to give context for ddoc's history. FWIW switching dlang and phobos now to doxygen would be a major effort and I'm not sure we'd be in a better place even after assuming perfect execution. I don't think the current documentation of phobos is affecting (professional) D adoption much, although it can improve a lot. Adoption is a language/compiler/runtime/tooling issue. On the other hand, if converting phobos' Ddoc into Doxygen cannot be automated, then that suggests that there is a fundamental problem with how Ddoc is used as a markup tool. Adopting Doxygen would give you some benefits: - it makes D look less weird - it makes it easier to use existing formatting/presentation solutions - it is more motivating to learn Doxygen than figuring out Ddoc since you can use it for non-D projects The Doxygen front page advertises the following: «it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.» D would look better without the "to some extend" and you might get the Doxygen community to help out with Doxygen relevant tooling issues if it is the default D documentation tool. Basically an opportunity for synergy.
Re: Improving ddoc
On 01/01/15 11:21, Andrei Alexandrescu via Digitalmars-d wrote: cd code/d/phobos git grep RPAREN | wc -l 28 It's a bugbear for std.random because I find myself writing things like: /** $(D uniform01) offers a faster generation of random variates than the equivalent $(D uniform!"[$(RPAREN)"(0.0, 1.0)) and so may be preferred for some applications. Returns: Floating-point random variate of type $(D T) drawn from the uniform distribution across the half-open interval [0, 1$(RPAREN). */ With respect to my other remarks in this thread, the example above is one of the single most annoying human-unreadable things I encounter: I would really, really like mathematics and inline code examples in the docs to not need "escaping" in this manner, so that it's as easy as possible to compare and contrast docs and code in the source file. I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(
Re: Improving ddoc
On Thursday, 1 January 2015 at 00:44:33 UTC, Adam D. Ruppe wrote: I'd actually prefer to focus more on ddoc's unique strengths - that it understands the compiler's scoping rules. If I understand this correctly, it seems very compelling to me. Would it be an option to 1. Work on ddoc (as it is now) to be even closer to the compiler (e.g. scoping rules) 2. Add a carefully selected markdown on top of proper ddoc (e.g. use ddoc instead of html as fallback) 3. Provide ddoc macro definitions to generate all kinds of output This would help in several ways 1. The fully functional ddoc system that can do books remains available. There is use for it. 2. The code documentation could be much more lightweight (but still have the full ddoc macros available if needed) 3. Generating to pandoc or the like. There are converters out there. If any of this is of any value, I am happy to help to make it happen.
Re: Improving ddoc
On 1/1/15 2:10 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote: But on a deeper note, perhaps the issue isn't really ddoc syntax per se, but the fact that doc comments can *only* be processed by ddoc. If there was a way to get the raw text out, the people who dislike ddoc can pipe it to the formatter of their own choice, and they would be happy. People who are indifferent will get ddoc by default, which, despite its flaws, isn't really *that* horrible. That's pretty much the very charter of ddoc- most misunderstood tool ever. Luckily I'll send some pull requests that simplify generation - some time next year :o) My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. For me it's very important that the documentation should be trivially comprehensible _when browsing source code_, and too often Ddoc markup prevents that. Got it. I think auto-macroizing would help with that. -- Andrei
Re: Improving ddoc
On 1/1/15 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote: One simple starter would be to allow one escape character, e.g. the backtick (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can write `MACRO arg1, arg2`. Would that be accompanied by deprecation and removal of the $(MACRO arg1, arg2) syntax? No. I ask because for me, one of the biggest annoyances of Ddoc (in terms of source readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc accidentally seeing a macro where there is none. cd code/d/phobos git grep RPAREN | wc -l 28 RPAREN is indeed more frequent in dlang.org: cd code/d/phobos git grep RPAREN | wc -l 589 Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The majority are in changelog.dd; I guess a couple of macros might help there. Andrei
Re: Improving ddoc
On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote: No particular system was clearly dominant when Walter invented ddoc. Also I might be frequenting the wrong circles; most people I know and myself aren't fluent at all with doxygen. -- Andrei It is really trivial to learn and quite effective. Totally. I did use it briefly a few years ago and I'm sure I can relearn it. My point here was to give context for ddoc's history. FWIW switching dlang and phobos now to doxygen would be a major effort and I'm not sure we'd be in a better place even after assuming perfect execution. Andrei
Re: Improving ddoc
On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote: But on a deeper note, perhaps the issue isn't really ddoc syntax per se, but the fact that doc comments can *only* be processed by ddoc. If there was a way to get the raw text out, the people who dislike ddoc can pipe it to the formatter of their own choice, and they would be happy. People who are indifferent will get ddoc by default, which, despite its flaws, isn't really *that* horrible. That's pretty much the very charter of ddoc- most misunderstood tool ever. Luckily I'll send some pull requests that simplify generation - some time next year :o) My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. For me it's very important that the documentation should be trivially comprehensible _when browsing source code_, and too often Ddoc markup prevents that.