ddox ignores methods defined in static if

[dcarp]

http://dlang.org/phobos-prerelease/std_array.html#.Appender describes 'clear' and 'shrinkTo' methods, but http://dlang.org/library-prerelease/std/array/appender.html don't.

[s-ludwig]

The root cause lies in DMD's JSON output, which is missing those fields. I'm actually surprised that they do end up in the documentation.

Apart form fixing/extending the DMD output, it would be possible to extend the experimental libdparse based back end to show such methods. In that case it would also be possible to display the condition(s) or version identifiers that apply to the enclosed declarations.

[CyberShadow]

Why would conditional compilation affect DDoc and JSON output in different ways?

[s-ludwig]

Good question. I don't know why, but it does:

///
module test;

///
struct Test(T) {
    static if (true) {
        ///
        void test();
    }
}

When compiled with dmd -o- -Dftest.html -Xftest.json test.d, the HTML output contains the test() function, while the "members" field for the Test struct in the JSON output is empty.

[yshui]

Hi, I'm trying to fix this problem. However, ddox seems to use some kind of heuristic (isTypeDecl?) to treat some template differently. So the end result is including static if's and version blocks will change some of the documents.

Example: new vs old

Do you think it's better for type templates to have kind = struct/class/etc., instead of kind = template in the JSON output, so you don't need to use this kind of heuristic?

[s-ludwig]

@yshui: The corresponding mechanic is in ddox.processors.eptemplates, which detects eponymous templates and merges the template definition with the contained declaration of the same name. It's a good question what should happen with eponymous templates that contain multiple alternative declarations inside. Displaying them as opaque "template" in the documentation in this particular case actually doesn't seem like the worst base approach actually.

Listing all possible declarations along with their condition would of course be much better. The eptemplates module would then have to be adjusted to search for all matching names and only convert templates to the contained declaration kind if there is only one.

Is there information about the static ifs themselves in the JSON output? Can you post a link to your changes? I'd be interested in having a quick look at the details.

[yshui]

@s-ludwig Change is dlang/dmd#6621. It just simply make the json generator do the same thing as the ddoc generator for static-if's and version blocks.

[schveiguy]

The original fix caused a different issue, but that is being worked on now (see here). After that is merged, I'd say this can be closed.