在注释中嵌入代码时从 appledoc 获取参考错误

Question

我有一些这样的代码：

/**
How to use this method.

@discussion To use it, do something like the following

    id hook = [[STDeallocHook alloc] initWithBlock:^{
        // Do something when 'hook' is dealloced
    }];
*/

所以代码示例缩进了 4 个空格。当我使用 appledoc 编译 docset 时，它会正确编译并将代码显示为我生成的 API 参考中的代码。但是回到 XCode（我有 appledoc 为 doco 中的问题创建警告的地方）我收到警告：

Invalid [[STDeallocHook alloc] reference found hear STDeallocHook.h@16, unknown object: [STDeallocHook !

我认为发生的事情是 appledoc 正在代码块内寻找降价链接。

如何阻止此警告出现？

Answer 1

我也无法阻止它。好像是known bug since 2011，但还是坏了。

有趣的是，我并不是每件事都能得到它。在一个大型代码示例中，我只会得到其中的几个......仍然没有弄清楚它是如何决定让我伤心的......

解决方法

这可以解决警告，并且在生成的文档中看起来不错，但在纯文本中看起来像废话：用 HTML 转义码 [ 替换前导 [

未来修复

据说，神话版本 3 已经解决了这个问题，但我找不到任何关于它的 ETA 的提及。 2012 年 3 月有一个 "3.0exp1" branch，2014 年 10 月有一个 "3.0dev" branch。

如果你有时间和兴趣，也许你可以看看它是如何修复的并自己修补它（尽管从那时起代码库显然已经改变了很多）。

我的尝试

我对这个答案感到不满意，所以，我回去查看了源代码。第一次在该代码中。导航不是很容易...而且没有记录任何类，我觉得这很奇怪，尤其是对于文档工具。

无论如何，我想我知道为什么我有时只会收到警告。解析器将所有下划线视为格式标记。因此，如果它在同一个文本“块”中找到它们中的两个，它会将它们拆分。由于我测试的代码有类别文档，因此只有在每个“块”中遇到的最后一个会导致警告...因为所有其他代码都被视为斜体...然后被忽略。

另外，如果源代码块被标记为...

，我似乎可以强制它跳过源代码块

@code
[self wjh_doSomething];
@endcode

或

```
[self wjh_doSomething];

```

或

~~~
[self wjh_doSomething];
~~~

第一个在文档块中很常见，后两个在markdown中。

这是一个 hack，但它似乎有效。我发送了一个 PR，which can be found here。谁知道它是否会被接受，但如果您愿意，请自行尝试。

我想我至少会在本地使用它，因为它会为我清除大量警告......我可能会尝试重新生成所有记录在案的内容以启动。

编辑

好吧，我想我应该先去看看公开的 PR。似乎有一个 PR already sitting there 处理相同的问题，自 5 月以来一直存在。它本来可以节省我的时间...但是尝试一下它有点有趣;-)

您可能想要使用那个...它似乎更简单。越简单越好，但我没有使用过那个，我不确定它是否完全忽略了这些块，但他似乎已经用他的补丁消除了警告。

那个不支持@code/@endcode，我很高兴拥有它。