d - 存在 `static if`时如何生成文档

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

使用dmd -D 编译，只为第一个 block 生成文档。我如何让它也为 else block 生成？

Answer 1

对于 version block ，它只是最终出现在文档中的版本(无论是第一个还是最后一个，或者两者之间的任何一个)。因此，例如，如果您有一个用于 Linux 的 version block 和一个用于 Windows 的 block ，那么只有与您编译的系统匹配的那个才会出现在文档中。

模板外的

static if block 似乎以相同的方式运行。如果它们被编译进去，那么它们的 ddoc 注释最终会出现在文档中，而如果它们没有被编译进去，它们就不会。

但是，static if block inside 模板似乎总是从第一个 static if block 中获取文档，即使它始终为 false。但是考虑到那些静态 ifs 最终可能同时为 true 和 false(来自模板的不同实例化)并且编译器实际上并不需要实例化模板它的 ddoc 注释最终出现在生成的文档中，这是有道理的。它没有像模板外的 static if block 那样只有一个正确答案。

无论如何，将文档放在 version block 或 static if 中通常不是一个好主意，因为它们使用的是条件编译，可能会也可能不会已编译。解决方案是使用 version(D_Ddoc) block 。所以，你最终会得到这样的结果:

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

我还要指出，即使您尝试做的事情奏效了，它在文档中看起来也会很奇怪，因为您最终会在其中两次使用完全相同的 foo签名但不同的意见。 static if 根本没有出现在文档中，因此无法知道 foo 在什么情况下存在。它看起来就像你以某种方式声明了 foo 两次。

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

然而，您不需要 version(D_Ddoc) 的地方是当您在一系列 version block 中具有相同的功能时。例如

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

无论在哪个 version block 中编译，ddoc 注释都将最终出现在生成的文档中。

应该注意的是，使用 version(D_Ddoc) block 往往会导致在使用 -D 时，为任何内容编译代码都没有意义除了生成文档之外，您运行的实际可执行文件应该由不使用 -D 的单独构建生成。您可以将完整代码放在version(D_Ddoc) block 中以避免这种情况，但这意味着重复代码，并且它不会真正与static 一起使用如果。 Phobos 使用 version(StdDdoc)(它为自己定义)而不是 version(D_Ddoc)，因此如果您不使用 version(D_Ddoc) block ，你仍然可以使用 -D 编译并让 Phobos 工作，但是一旦你开始使用 version(D_Ddoc)，你将不得不生成你的文档与您的正常构建分开。