digitalmars.D.bugs - [Issue 11337] New: Ddoc ignores methods in static else block
- d-bugmail puremagic.com (28/28) Oct 24 2013 http://d.puremagic.com/issues/show_bug.cgi?id=11337
- d-bugmail puremagic.com (7/7) Oct 24 2013 http://d.puremagic.com/issues/show_bug.cgi?id=11337
- d-bugmail puremagic.com (28/28) Oct 24 2013 http://d.puremagic.com/issues/show_bug.cgi?id=11337
- d-bugmail puremagic.com (39/39) Oct 24 2013 http://d.puremagic.com/issues/show_bug.cgi?id=11337
http://d.puremagic.com/issues/show_bug.cgi?id=11337 Summary: Ddoc ignores methods in static else block Product: D Version: D2 Platform: All OS/Version: All Status: NEW Severity: normal Priority: P2 Component: DMD AssignedTo: nobody puremagic.com ReportedBy: joseph.wakeling webdrake.net 2013-10-24 02:03:14 PDT --- Created an attachment (id=1283) Example code illustrating the bug: ddoc entry in a static else block is not used In the event that a static if {} else {} block is used to determine what methods belong to a struct/class, Ddoc will ignore the documentation for methods defined in the if {} block. The attached code shows 2 different classes: one where two different functions are defined depending on a static if/else block, another where the same effect is achieved with two static if blocks (static if (cond) { ... } static if (!cond) { ... }). In the first case, the second function is not picked up by ddoc; in the second, it is. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Oct 24 2013
http://d.puremagic.com/issues/show_bug.cgi?id=11337 2013-10-24 02:13:38 PDT --- N.B. as an ideal case, it should be possible to use /// ditto comments in the else {} block, and have them pick up on whatever methods precede them. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Oct 24 2013
http://d.puremagic.com/issues/show_bug.cgi?id=11337 Jonathan M Davis <jmdavisProg gmx.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |jmdavisProg gmx.com PDT --- If anything, I would say that the fact that Coin2 shows both is the problem rather than the fact that Coin1 shows only one. In neither case can both exist, and normally, ddoc only shows the code that gets compiled in (e.g. versioned out code will not show up in the generated documentation). Normally, when you get something weird like this, you use version(D_Ddoc) blocks to make the documentation show what you want, but it's not particularly correct for it to blindly throw everything for all of the various static if branches into the documentation. The result wouldn't look anything like the actual class. I think that it's getting a bit weird here because while the compiler normally doesn't show stuff in the documentation that isn't compiled in, it tries to show templated stuff even if it's not compiled in. And because it's then generating documentation for a template which isn't associated with a particular instantiation, it doesn't actually know what is and isn't supposed to be compiled in. If those static ifs were outside of a template, then only the branches which were true would end up with the documentation being generated for them. So, the template just makes things weird. It also makes it much harder to even know what the correct thing to do with the documentation is, because what the documentation should look like could depend on the template arguments (as is the case here). -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Oct 24 2013
http://d.puremagic.com/issues/show_bug.cgi?id=11337 2013-10-24 07:30:05 PDT --- Hmm, I appreciate what you're saying but for me it's logical that you should be able to document templated code in complete fashion, i.e. that you should be able to document every possible member function and that it should be clear what will occur under which circumstances. I don't see how else one could reliably generate documentation for a Boost-style "header-esque" library. The particular motivation for me is this: https://github.com/WebDrake/Dgraph/blob/141c8e2cd40376be2237b7d0bee6d73af75fbc0e/source/dgraph/graph.d#L253-L290 ... where I have different functions defined in a class depending on a template parameter, but where I'd like them all to be documented. I'm happy for suggestions as to how to alternatively do that, but it just seems a bit odd that if stuff inside any kind of static if is displayed _at all_ without explicit instantiation, that stuff inside the "if" is displayed but not stuff from the "else". Note that another way to define Coin would be something like, /// Yet another coin struct Coin3(bool heads) { /// Coin shows heads void head()() if (heads) { } /// Coin shows tails void tail()() if (!heads) { } } ... which documents both functions, but also includes the template if constraint. Could ddoc be re-worked to do something similar for stuff inside a static if/else? The problem with this 3rd approach is that it makes head and tail both part of the public API, regardless of the underlying boolean value of heads; it's _calling_ one of them that will fail. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Oct 24 2013