标签: headerdoc

我需要为我的工作场所实施文档生成解决方案,并将其缩小到标题中提到的三个.我已经能够在这些解决方案之间进行正式比较的方式中找到很少的信息,我希望那些在上述一个或多个方面有经验的人可以权衡:

以下是我从初次传球中收集到的内容:

HeaderDoc优点:与苹果公司现有的文档一致,与制作苹果文档集的兼容性
HeaderDoc缺点:难以修改行为,项目没有积极处理,许多人已经转离它(意味着必须有一些不足之处,尽管我无法量化它).

Doxygen Pros:活跃支持社区b/c广泛使用基础,非常可定制,大多数输出​​类型(如乳胶等)
Doxygen缺点:工作使其外观/行为与apple docs一致,与apple docsets的兼容性并不那么简单

AppleDoc专业人士:看起来与苹果现有的文档一致,与制作苹果文档集的兼容性,
AppleDoc缺点:有关typedef,枚举和函数文档的问题,正在积极开发中

这听起来准确吗？我们理想的解决方案将:

• 苹果Objective-c类参考的一致外观
• 能够选项单击以从Xcode中提取文档引用,然后链接到doc(就像苹果的类)
• 智能处理类别,扩展等(甚至是苹果类的自定义类别)
• 能够创建我们自己的参考页面(比如这个页面:Loading ...可以包含图像,并且可以无缝地链接生成的类引用,就像apple的UIViewController类引用链接到链接页面一样.
• 易于运行的命令行命令,可以集成到构建脚本中
• 优雅地处理非常大的代码库

根据以上所有信息,上述任何一种解决方案明显优于其他解决方案吗？任何建议或信息,将非常感激.

我尝试使用HeaderDoc在Xcode中记录我的Swift项目,但只处理文件".h"并忽略文件".swift"

这是我的swift文件:

/// test
///
/// :param: ann blabla
func testFunc( ann: Foo ) { .. }

我在终端中运行以下命令:

headerdoc2html -o ~/Desktop/docum Ninja

This is the error:

    Documentation will be written to /Users/me/Desktop/docum
    HTML output mode.
    No valid input files specified. 

        Usage: headerdoc2html [-dq] [-o <output directory>] <input file(s) or directory>.

    iMac:MyApp me$  headerdoc2html -o ~/Desktop/docum Ninja/

    Documentation will be written to /Users/me/Desktop/docum
    HTML output mode.
    DIR Ninja/
    ======= Parsing Input Files =======

    Processing Ninja/Test.m
        Skipping. No HeaderDoc comments found.

    Processing …

我已经看到Apple的HeaderDoc用户指南已被标记为"已退休文档",并附有以下注释:

重要提示:本文档可能并不代表当前开发的最佳实践.下载和其他资源的链接可能不再有效.

该文件最后更新于5月.那么......现在在Xcode 8中记录代码的最佳实践是什么？我没有找到关于此的进一步信息.

我通常需要在代码注释中编写许多短代码this.这可以在Apple的Headerdoc中使用吗？因为这种类型的代码符号通常被大量使用,所以我相信有一种方便的方法来执行此操作而不是标记HTML标记.

我在XCode中使用headerDoc标签,似乎无法记录.m文件中的私有方法.直接从Apple的网站使用示例语法:

@implementation AppDelegate

/*!
 This is an objective-C method.
 @param application
 Parameter A.
 @param launchOptions
 Parameter B.
 @result
 Results in global warming.
 */

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

}

导致以下错误:

Processing compassview/AppDelegate.m
/Users/me/workspace/iOS/myapp/AppDelegate.m:inputCounter: warning: Class braces do not match.
We may have a problem.
/Users/me/workspace/iOS/myapp/AppDelegate.m:194: WARNING: anonymous type.
IC: 181
DC: "end  
"
TL: ""
NL: "end"
PT: ""
/Users/me/workspace/iOS/myapp/AppDelegate.m:194: warning: Unknown keyword  in block-parsed declaration.
This usually means that your code requires C preprocessing in order to be …

我正在使用HeaderDoc来记录我的代码,我想链接到文档中的其他方法.我不是想生成HTML(至少目前为止),但我确实希望它出现在Xcode的右侧面板中.以下是-applicationDidEnterBackground:Xcode中出现的文档.我想实现那些引用我自己编写的其他方法的蓝色链接:

文档说要使用@link,但它似乎不起作用:

这是我试过的:

/**
 *  @abstract   Returns an array with a copy of all elements in the heap in sorted order.
 *
 *  @discussion The original heap remains unchanged. This getter uses Heap Sort which takes O(n log n),
 *              although it copies the heap first (in linear time). If losing the elements on the heap is
 *              acceptable you should use @link -removeAllObjectsWithArray: @/link instead, which is faster.
 */

这是结果:

你可以看到它没有正确渲染.我在这里读到的内容@link已经破了,但评论可以追溯到2013年.有没有修复？我做错了吗？ …

由于XCode 5现在支持直接从头文件读取标题注释,因此以一致的方式记录功能变得越来越有趣.

因此,我试图找到一个工具,可以在Objective C头文件中自动插入标题文档注释,但似乎找不到一个？

基本上我想要一个可以写如下的东西:

/*!
    <desc method.>
    @param parmA
        <desc of parmA>
    @param parmB
        <desc of parmB>
    @result
        <desc of result>
 */
- (CO2 *)doSomething:(typeName)parmA withSomething:(typeName)parmB;

我们目前正计划使用注释来创建文档。所以任何人都知道如何实现这一目标。正如我检查过的大部分帖子，Doxygen/headerdoc 不支持 Swift。

我正在为iOS应用程序开发一个可重用的API组件.我已经完成了API并将其记录下来以headerdoc供将来的用户使用.

现在我想为这些头文件创建HTML页面.所以我在我的项目目录中的终端中执行了以下命令

headerdoc2html -o ~/Desktop/My_Project_Documentation APIFolder/

但是没有创建文档,而是我收到的错误如下:

Skipping. No HeaderDoc comments found.
No default encoding.  Guessing.  If date formats are wrong, try
specifying an appropriate value in the LANG environment variable.
...done

我尝试了各种方法和方法,最后我缩小了问题的范围:

在我的项目开始时,我有类似的东西:

/**
 *  DarkPantherConstants.h
 *  Panther
 *  Created by Midhun on 05/11/14.
 *  Copyright (c) 2014 Midhun. All rights reserved.
 *  Panther Constants are defined in this header file
 */

所以问题在于这个特别的评论,实际上这个评论是由XCode自动生成的,我实际上修改了名称和评论格式headerdoc.没有日期或日期格式.即使我删除这些评论,也没有任何作用; 得到同样的错误.有人可以帮我解决这个问题吗？