D 存在`静态if'时如何生成文档`

使用

dmd-D

编译时，仅为第一个块生成文档。如何让它也为

else

块生成？

对于

版本

块，只有使用的版本才会出现在文档中（无论是第一个版本还是最后一个版本，或者介于两者之间）。因此，例如，如果Linux有一个

version

块，Windows有一个

块，那么文档中只有与编译系统匹配的块

static if
模板外的块似乎以同样的方式工作。如果他们在中编译，那么他们的ddoc注释最终会出现在文档中，而如果他们没有在中编译，则不会

但是，模板中的
static if
块似乎总是从第一个静态if块抓取文档，即使它总是
false
。但考虑到这些静态ifs最终可能同时是
true
和
false
（来自模板的不同实例化），并且编译器实际上不需要为其ddoc注释在生成的文档中结束而实例化模板，这是有意义的。它没有一个正确的答案，比如
static if
模板之外的块

无论如何，将文档放在
版本
块或
静态if
块中通常是一个坏主意，因为它们使用的是条件编译，并且可能在中编译，也可能不在中编译。解决方案是使用
版本（Ddoc）
块。所以，你最终会得到这样的结果：

/** 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() { }
  }
}

我还要指出的是，即使你试图做的事情成功了，在文档中看起来也会很奇怪，因为你会在那里两次出现
foo
，并且有完全相同的签名，但注释不同<如果

根本没有出现在文档中，则代码>静态，因此无法知道在什么情况下存在

foo

。它看起来就像你两次声明了

foo

这种情况与模板约束类似。约束不会最终出现在文档中，因此在处理仅由约束重载的模板函数时，记录每个函数重载是没有意义的

但是，您不需要

version（D_Ddoc）

的一个地方是，当您在一系列

version

块中具有相同的功能时。e、 g

/// 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() { }
        }
    }
}

无论编译的是哪个

版本

块，ddoc注释都将在生成的文档中结束

应该注意的是，当使用

-D

时，使用

version（D_Ddoc）

块往往会导致这样的情况，除了生成文档之外，编译代码是没有意义的，您运行的实际可执行文件应该由不使用

-D

的单独构建生成。您可以将完整的代码放在

版本（D_Ddoc）

块中以避免这种情况，但这意味着重复代码，如果

是静态的，那么它就不能真正工作。火卫一使用
version（StdDdoc）
（它自己定义的）而不是
version（D\u Ddoc）
，因此，如果您不使用
version（D\u Ddoc）
块，您仍然可以使用
-D
编译并让火卫一工作，但一旦您开始使用
version（D\u Ddoc）
，您将不得不从正常构建中单独生成文档

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