在注释中嵌入代码时从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中。

这是一个黑客，但它似乎工作。我发了一封PR，which can be found here。谁知道它是否会被接受，但如果你这么倾向，可以自己尝试一下。

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

修改

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

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

那个人不支持@ code / @ endcode，我很高兴。