Question

/** This is struct S. */
struct S(T) {

  static if(isFloatingPoint!T)
  {
    /// This version works well with floating-point numbers.
    void fun() { }
  }
  else
  {
    /// This version works well with everything else.
    void fun() { }
    /// We also provide extra functionality.
    void du() { }
  }
}

Compiling with dmd -D, documentation is generated for the first block only. How do I get it to generate for the else block as well ?

Answer 1

For version blocks, it’s only the version which is used which ends up in the documentation (be it the first one or the last one or whichever in between). So, for instance, if you have a version block for Linux and one for Windows, only the one which matches the system that you compile on will end up in the docs.

static if blocks outside of templates seem to act the same way. If they’re compiled in, then their ddoc comments end up in the docs, whereas if they’re not compiled in, they don’t.

However, static if blocks inside templates appear to always grab the documentation from the first static if block, even if it’s always false. But considering that those static ifs can end up being both true and false (from different instantiations of the template) and that the compiler doesn’t actually require that the template be instantiated for its ddoc comments to end up in the generated docs, that makes sense. It doesn’t have one right answer like static if blocks outside of templates do.

Regardless, it’s generally a bad idea to put documentation inside of a version block or static if, precisely because they’re using conditional compilation and may or may not be compiled in. The solution is to use a version(D_Ddoc) block. So, you’d end up with something like this:

/// This is struct S
struct S(T)
{
    version(D_Ddoc)
    {
        /// Function foo.
        void fun();

        /// Extra functionality. Exists only when T is not a floating point type.
        void du();
    }
    else
    {
        static if(isFloatingPoint!T)
            void fun() { }
        else
        {
            void fun() { }
            void du() { }
        }
    }
}

I would also note that even if what you were trying to do had worked, it would look very bizarre in the documentation, because you would have ended up with foo in there twice with the exact same signature but different comments. static if doesn’t end up in the docs at all, so there’d be no way to know under what circumstances foo existed. It would just look like you somehow declared foo twice.

The situation is similar with template constraints. The constraints don’t end up in the docs, so it doesn’t make sense to document each function overload when you’re dealing with templated functions which are overloaded only by the their constraints.

One place where you don’t need version(D_Ddoc), however, is when you have the same function in a series of version blocks. e.g.

/// foo!
version(linux)
    void foo() {}
else version(Windows)
    void foo() {}
else
    static assert(0, "Unsupported OS.");

The ddoc comment will end up in the generated documentation regardless of which version block is compiled in.

It should be noted that the use of version(D_Ddoc) blocks tends to make it so when using -D, it makes no sense to compile your code for anything other than generating the documentation and that the actual executable that you run should be generated by a separate build which doesn’t use -D. You can put the full code in the version(D_Ddoc) blocks to avoid that, but that would mean duplicating code, and it wouldn’t really work with static if. Phobos uses version(StdDdoc) (which it defines for itself) instead of version(D_Ddoc) so that if you don’t use version(D_Ddoc) blocks, you can still compile with -D and have Phobos work, but once you start using version(D_Ddoc), you’re going to have to generate your documentation separately from your normal build.