在注释中嵌入代码时从 appledoc 获取引用错误
Getting reference error from appledoc when embedding code in comments
我有一些这样的代码注释：
/**
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 正在寻找代码块内的降价链接。
如何阻止此警告的出现？
我也忍不住了。看起来已经是 known bug since 2011，但还是坏了。
有趣的是，我并不是什么都明白。在一个大的代码示例中，我只会得到其中的一些......仍然没有弄清楚它是如何确定是否让我悲伤的......
解决方法
这解决了警告问题，在生成的文档中看起来不错，但在纯文本中看起来像废话：用 HTML 转义码 [[ 替换前导 [ =19=]
未来修复
据说，神话版本 3 已经解决了它，但我找不到任何提及它的 ETA。有一个 "3.0exp1" branch from March 2012, and a "3.0dev" branch 从 2014 年 10 月开始。
如果您既有时间又有兴趣，也许您可以看看它是如何修复的并自己修补它（尽管从那时起代码库显然已经改变了很多）。
我的尝试
我对这个答案感到不满意，所以，我回去查看了源代码。第一次使用该代码。浏览起来并不容易...... 类 的 none 被记录下来，我觉得这很奇怪，特别是对于文档工具。
无论如何，我想我知道为什么我有时只会收到警告。解析器将所有下划线视为格式化标记。因此，如果它在相同的 "block" 文本中找到其中两个，则会将它们分开。由于我测试的代码有类别文档，只有最后一个在每个 "block" 中遇到导致警告...因为所有其他的都被视为斜体...然后被忽略。
此外，如果它们被标记为...，我似乎可以强制它跳过源代码块...
@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，我很高兴。
我有一些这样的代码注释：
/**
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 正在寻找代码块内的降价链接。
如何阻止此警告的出现？
我也忍不住了。看起来已经是 known bug since 2011，但还是坏了。
有趣的是，我并不是什么都明白。在一个大的代码示例中，我只会得到其中的一些......仍然没有弄清楚它是如何确定是否让我悲伤的......
解决方法
这解决了警告问题，在生成的文档中看起来不错，但在纯文本中看起来像废话：用 HTML 转义码 [[ 替换前导 [ =19=]
未来修复
据说，神话版本 3 已经解决了它，但我找不到任何提及它的 ETA。有一个 "3.0exp1" branch from March 2012, and a "3.0dev" branch 从 2014 年 10 月开始。
如果您既有时间又有兴趣，也许您可以看看它是如何修复的并自己修补它（尽管从那时起代码库显然已经改变了很多）。
我的尝试
我对这个答案感到不满意，所以，我回去查看了源代码。第一次使用该代码。浏览起来并不容易...... 类 的 none 被记录下来，我觉得这很奇怪，特别是对于文档工具。
无论如何，我想我知道为什么我有时只会收到警告。解析器将所有下划线视为格式化标记。因此，如果它在相同的 "block" 文本中找到其中两个，则会将它们分开。由于我测试的代码有类别文档，只有最后一个在每个 "block" 中遇到导致警告...因为所有其他的都被视为斜体...然后被忽略。
此外，如果它们被标记为...，我似乎可以强制它跳过源代码块...
@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，我很高兴。