创build好的API文档：工具和技术
我的任务是创build一个Web服务，这个服务将被几个不同的开发者使用，使用不同的平台，为不同的公司工作，而且技术水平差异很大。 因此，我想创build这个Web服务API的文档，这是既完整，也很容易理解。 尽pipe我确信这是所有文档项目试图实现的高尚目标，但我还没有find最好的工具和/或工作stream程来帮助我的项目达到目标。
你在创build优秀的API文档时发现哪些工具和技术最有用？
您是否发现自动生成的文档工具足以为最终用户提供使用您的服务所需的所有信息？
您是否发现基于Wiki的工具既简单又快速，以维护最新的API文档？
你有没有发现任何提供“两全其美”的自动化和灵活性的工具或技术？ 是否存在任何工具来简化API的多个版本的文档化过程？
我已经完成了博士学位。 在Java中的API文档。 Web服务明显不同，但我相信一些发现是全球性的。
首先，你必须接受这样一个事实，即你将有两个“class级”的读者。 一个小class是那些为每个function都做完整读写的人。 与Java一样，您希望每个“函数”都能完美地指定您的API文档。 你不希望你的用户（或互联网论坛）猜测。 不幸的是，这个class级相当小，而且经常发生在关键任务客户或有组织的代码审查。
API文档用户更常见的forms是“我只想完成事情”types的人。 他（或她）有他们想要完成的概念。 他们也有在哪里find它的想法，所以假设他们已经find了你的function。 这里是问题的起点 – 他们并不真的想要阅读文档。 现在假设你的电话有五个参数，四个显而易见，但有一个告诫（例如，“只发送一个公开的会话”）。 如果你仔细阅读参数列表，并完整地指定每个参数，他们会疲惫不堪，不会注意到关键的事情。 我不能强调这一点 – 人们完全不会注意到他们面对的东西。 这变得更加棘手 – 如果他们相信他们完全理解函数，即使他们懒得去阅读文档，他们也会 – 很可能 – 跳过它。 我看到人们对两句话文档的方法缺less明显的警告。
所以这里是你可以做的：
-
假设大多数用户不会真正阅读他们所调用函数的文档。 事实上，API越直观，有人读取文档的可能性就越小。 每个人都会读一个奇怪的名字和20个参数的函数。 但是如果你写了一个非常简单的API并且有一个令人讨厌的警告，那么你就冒着从不被阅读的风险。 唯一的解决办法（我有一些Java，但不是为了networking）是为了避免意外。
-
当你写完整的完整的API时，明确地突出显示一些不重要的部分（我可以向你展示Java中令人吃惊的整个分类，很多翻译）。 更好的是，有三个人看文档，拿起不直观的东西。 如果您不能将它们排除在API之外，请突出显示它们。
最后（也可以参考Jeff Stylos，他也是API的博士学位）：提供某些操作的配方（甚至作为一个单独的网页），并考虑在文档文本中创build“占位符”不是API的一部分，但是用户会很乐意。 例如，如果许多用户想要执行Z，但是在API中执行此操作的方法是先执行X，然后再执行Y，则在文档中添加一个“do Z”占位符，并特别告诉它们调用X和Y.
一对夫妇logging技术，我已经学会了艰辛的方式：
- 语法图 （特别是铁路图）提供了一个非常清晰，可读的方式来描述命令和选项的语法。
- 始终为您使用的每个function/概念至less提供一个示例。 优选地，包括简单的使用和复杂的使用。
- 使用倒金字塔书写风格 – 首先提供最重要的信息，然后逐渐不重要！ 这可以让你的用户根据他们所需要的细节select多远来阅读。 也适用于整体文档 – 在第一部分给出概念，并保存到最后的确切细节。
- 教程或样本是必不可less的，既不平凡也不过分复杂！
- 不要强迫你的用户学习你自己的括号，大括号，尖括号和粗体/斜体/下划线/间距的系统来阅读你的文档。 是的，你应该有一个一致的系统，但是它应该遵循一个通用的约定，或者最好是在可能的情况下使用语法图。
几个星期前，我提出了一个开源代码文档标准，它提供了一些宽松的指导原则来logging开源代码。 Jacob Kaplan-Moss也撰写了一系列关于这个问题的文章 。 简而言之，我相信大部分 API都可以通过以下几个部分得到很好的logging：
- 它是什么，为什么你可能想要使用它
- 如何下载/购买，安装和configuration
- 如何开始使用它（一个教程）
- 如何用它做更高级的事情（专题指南）
- API文档（自动生成）
这些部分可能不是在同一个地方发布（他们可能在不同的网站上），或者使用相同的工具（wiki，auto-doc generator等）创build，但是每个部分都应该可以通过其他部分的链接直接访问（每个源的顶部应该有一个目录）。 这允许您为文档的每个部分使用最合适的工具，并且仍然处理所有相关的区域。
我认为这样的多工具方法是必要的，因为：
- 自动生成的文档跟上最新的API，但对初学者没用
- 维基涉及到社区，但无法跟上频繁的API更改
- README文件太静态
同样，只要每个部分都可以从其他部分访问，我认为使用多个工具/站点是logging大部分时间的最佳方式。
同意先前几个海报的观点，许多用户不会阅读文件。 根据我的经验，有三种方法可以将文档一起使用，形成一个非常有用的工具。
第1层：自我logging代码尽可能使您的API尽可能less的文档。 按照（并发布）命名约定为您的function，参数和数据types，使其目的显而易见。 最好的文档是不需要的文档。
第2层：演练/示例代码虽然很多人不会通过API文档阅读，通过示例代码阅读通常被认为是不那么痛苦（和一些，更有帮助）。 创build一些简单，直接的示例，使用您的API并分别从您的API文档发布它们。 覆盖尽可能多的常见使用场景。 虽然这不会为用户提供与学习API相同程度的知识，但至less会为许多用户提供一个起点。 即使他们只是简单地剪切和粘贴示例代码，并将其用作自己的骨架，他们也将从已知的工作代码开始，并且将减less您收到的“初学者”问题和支持请求的数量。
第3层：详细的，始终更新的文档无论是否有很多人阅读，总是有一个详细的，全面的文档可用。 为此，我更喜欢使用文档生成器，如Doxygen 。 如果你有某种自动化的构build过程，这个效果特别好。 对于我们的项目，我们有一台服务器，每天晚上build立并重新生成项目文档。 这样，每个人都可以在网上查看最新的文档。
文件发生器有几个优点。 首先，随时保持文档最新是很容易的。 由于生成器在源代码中使用注释和符号来创build它们的输出，所以使用文档生成器也鼓励开发人员彻底并适当地logging他们的代码（这样文档就在源代码和外部文档中，而且你只需要编写它一旦）。 如果您的项目包含多个分支，或者您的开发人员在您的代码的多个不同版本上工作，则文档生成器可以为正在使用的任何特定版本的源代码创build文档。 另外，自动生成的文档不需要任何额外的工作来备份或存档（因为它可以从您保存在版本控制库中的源代码重新创build，对吗？）。
根据我的经验，提供这三个层次的文档会产生最好的结果。 那些想要阅读文档并学习API的人可以这样做，而那些不懂的人可以很好地获得。 从你的angular度来看，这个方法也只需要很less的努力。 第一层是许多软件项目已经做的事情。 第二层通常是复制已经写好的代码段，简化它，并将其发布到网站或维基上。 第三层可能需要一些工作来重新格式化现有注释，以遵循文档生成器期望的约定; 然而，Doxygen（也可能是其他的）即使不添加任何Doxygen格式的注释也可以生成相当体面的文档。
有几件事要考虑：
无论你采取什么方式，确保当你发布xy版本的软件，你也可以发布版本 xy的文档。 大多数基于wiki的方法只是跟踪头部，并迅速变得毫无用处，任何人都不愿意使用旧版本的API（好吧，如果你是一个web服务，只是要强制所有用户升级，这可不是什么问题）。 您希望鼓励用户提交错误文档（文档将包含错误），就像他们将其提交给软件本身一样容易，并跟踪您的BTS /版本控制中的编辑，就像您的软件错误。 同样，维基文档的一个问题似乎是，即使您授权最终用户对其进行编辑，他们也不觉得合格，也没有人提交对维基文档的错误，所以错误不会得到修复。
提供说明性的工作代码示例（并将代码示例作为构build和testing系统的一部分进行testing）。 大多数开发者最初会比那些function不同的API描述更感兴趣，如果样本是好的，很多人都不会再看。
如果您在线托pipe文档，请使用Web分析工具查看用户正在阅读的内容。 把努力投入到人们认为有用的东西上。
至于这些工具，我所使用的所有公司都使用他们自己的工具（他们自己的工具与一些第三方工具的组合）来构build文档。 我想这意味着一个非常好的通用工具不存在或者很难find。
至于技术……对我来说真的很好的一个是：
- 让每个开发者写文档评论。 在每个版本中创build一些自动生成的文档。 设置构build，以便丢失的文档注释成为错误。
- 聘请专业的技术作家从这些自动生成的文档中创build可读的文档。 一个非常好的作家将会确定最有可能被客户使用的类和方法。 由于编写者本身并不直接参与创buildAPI，所以他们经常拿出比开发者更容易理解的例子。
- 设置一些反馈系统，通知作者API的变化。 所以，如果你添加/删除/更改方法，作者可以通知有关。
- 例子，例子，例子。 人们喜欢的例子。 find一种方法，如何尽可能提供示例，从简单到高级。
- 给读者提供一些方法来提供对文档的评论。 您不一定需要维基，但要确保您可以获得并纳入反馈。 另外，让人们知道你的文档是通过他们的请求来改变的，这会增加有用的反馈。
希望这可以帮助。
您是否发现自动生成的文档工具足以为最终用户提供使用您的服务所需的所有信息？
不，通常这些工具使用的代码注释中缺less很多细节。 见下文。
您是否发现基于Wiki的工具既简单又快速，以维护最新的API文档？
不，有人必须出示文件，通常是编码员。 编码人员并不总是精通撰写文档，这是wiki格式所要求的。 见下文。 此外，维基不会为了“logging多个版本的API”
你有没有发现任何提供“两全其美”的自动化和灵活性的工具或技术？
XML模板
是否存在任何工具来简化API的多个版本的文档化过程？
源代码pipe理。 Darcs或者Git等等。
你在创build优秀的API文档时发现哪些工具和技术最有用？
简单地说：使你的API文档本身成为代码。
大多数人犯的最大错误是要求编码人员编写文档……就像要求文档编写者编写代码一样。 它们并不一定会讨厌它（尽pipe情况可能如此），而是他们并不精通它。 这不是他们的核心能力。 所以不pipe你使用什么工具或最好的方法，你都会得到低质量的输出，因为编码器不是编写文档的专家。
但是，编码器是最适合loggingAPI的编码器。 因此，您必须将API文档化为编码function。 现在大多数人都知道了，说好的，让我们使用代码注释，并从这些注释中自动生成我们的API文档。 不好。 现在，您不能将API文档视为可交付成果。 它被集成到代码本身，你不能修改它，而无需触摸代码库。 编码器会看到评论旁边的代码，并认为代码本身就是明显的，并且尽可能减less（或者潜意识地）评论/文档细节，而不是处理各种不自觉的警告，除非你正在查看代码本身。 除了其他许多原因外，还有一些是为了避开这条路。
所以，需要的心态是这样形成的：
- 将API文档视为代码项目
- 编码器应该能够访问API文档的“代码”，并且可以像编码一样方便地进行修改。 这意味着它必须是一个纯文本文件，可以在他们最喜欢的编辑器/开发环境中进行编辑。
- 编码器用于语法正确性和编译器/语言的限制。 因此，请使用需要并强制执行特定内容区域的模板系统。 基本的XML是一个开始。
- 作为API文档项目的一部分，保留翻译脚本（XML到任何地方），并鼓励编码人员改进这些脚本…即给他们一些玩的东西。 （可选，但实际上有助于长期生成更好的文档）
- 每个APIfunction应logging在其自己的源文件中。 不要将多个文档单元放在一个文件中。 这样可以让编码人员简单明了，避免陷入“文档”中。
- 像普通项目一样设置任务，里程碑等。 不要将API文档完全包含在您正在logging的主项目中。 这有助于有效性和重点输出，并帮助避免排队或最小化 – 哦，我们只需要一天的时间写文档咳嗽 。 非常多的心态问题，但它可以是一个有效的方法。
我发现一个实现很好的实现是使用XSL转换，以XML模板和CSSinput来生成XHTML输出。 很简单，看到的结果和容易调整。 这对于devise人员来说也很容易产生令人满意的布局/寻找文档而不必触摸文档本身。
采取这种方法和思路，我们现在可以版本控制我们的文档，修改它，发布更新，让开发人员工作，并像对待其他编码项目一样对待它。 可以针对项目提交错误并发布。 等等等等。如果你使用了一个好的源代码控制工具，那么为各种版本的API维护文档是一件轻而易举的事情。
我认为，如果你在创buildAPI的控制，最好从头开始考虑可用性 （devise一个可用的API – 我在这里谈论的编程心理学研究领域，而不是无偿的意见），而不是关心仅仅用于logging它的可用性。 即API可用性与API文档的可用性严格相关，但并不完全相同 – 至less这是我从经验和对这个主题的一些阅读的印象。
Uri Dekel （也在这里 ）在这个主题的详细答案是非常有趣的，我希望它（和杰夫Stylos）论文将很快在networking上的某个地方。
同时，请查看The API Usability project @ CMU，尤其是eSOA API子项目（同一页底部）的可用性。 有几篇论文证实了我的假设：API可用性和文档可用性是不同的问题：
- 重新deviseAPI以提高可用性的案例研究;
- 通过用户研究改进 eSOA API的文档 。
所以你更好地注意两者。
还有这个网站致力于API可用性 ：它有一个参考书目的资源部分 。
CodeProject上有一篇关于API可用性的文章，似乎已经被充分的了解和编写。
高级技术作家汤姆·约翰逊（Tom Johnson）有一篇关于文档可用性的博文 。
等等..一个简单的networkingsearch“API可用性”和“networking服务”提供了更多的材料可供select。
PS：select一个合适的文件工具是国际海事组织最后一个关注的问题。
简介 ：使用编译器从文档本身生成API存根。
警告 ：不是一个便宜的解决scheme，但谁说你现在可以得到一个免费的午餐。
提示 ：使用flex / bison生成API存根生成编译器。
如果您想要一种方法来良好地logging您的API，那么您正在跟踪。 有无数的API文档不好，迫使用户直接去源（一个罕见的用户那个），或者干脆放弃，find替代品。
编写API文档的一个大问题是，随着时间的推移，它们会与实现不同步。 例如，开发人员修改API以接受额外的参数，可能不记得更新函数的文档。 所以，即使生成了新的API的文档，它可能会与实际的实现不同步。
我们通过从文档本身生成API存根来解决这个问题，即文档指定了API接口。 Docs在存根生成编译器所理解的语法中进行了描述。 编译器确保每个参数都有文档logging，并且有描述API的注释，并生成存根文件以及格式化的文档。 存根由开发者填写。
如perf.api
######################################################################### @arg1(string): Blah blah blah @arg2(string): Blah blah blah @perfcounter: Provides a cli interface to get back performance counter. @return(int): perf counter value ######################################################################### 编译：
> stubcc perf.api generated perf.h generated perf.c
生成的perf.c文件：
#include "perf.h" int perfcounter_stub(char *arg1, char *arg2) { return perfcounter(arg1, arg2); }
生成的perf.h文件：
#ifndef PERF_H #define PERF_H extern int perfcounter(char*, char*); #endif
开发人员在一个单独的文件中实现了perfcounter（）。
这确保了API文档始终是最新的，而且文档是由编译器执行的。 当然，如果你愿意，你仍然可以很糟糕地loggingAPI，但是你永远不会忘记logging某些东西。 为了确保文档质量，我们有一组单独的人员来审查文档的质量（与开发人员合作，了解他们想要logging的内容，并build议改进/更正等）
一个初步的观点是，如果你过于复杂的文件处理，那么你和后来的贡献者不太可能使用它。 如果有一个学习曲线来logging您的项目，那么您已经在与目标受众沟通的方式上设置了障碍。 维护文档过程本身可能成为一个耗时的项目。
正如已经指出的那样，有不同的受众，用各自独立的工具制作单独的文件是合适的。 作为一个最低限度，你需要两个文件：
-
“10,000英尺的视图”文档解释了API支持的结构，function和stream程，其中的重点在于为更详细的文档提供背景信息，很less有用户真正想读懂所有的智慧词汇，所以当他们还有一个问题：“我该如何做X”，你需要让他们知道“看Y组件”，这样他们才能切入到追逐中。如果你可以生成几个图来使核心结构是人们可以想象的东西，有大量的选项，但Wiki提供了一种方式来托pipe任何这样的文档，使用户可以贡献，并让你知道他们觉得需要扩展的领域。
-
详细说明每个调用，响应，参数和数据types的底层文件。 这样的文档的最好的特点是确保它是全面交叉链接和最新的。 当我查看给定的调用时，我希望能够通过点击鼠标来引用每个数据types，每个相关的调用和API的任何其他细节。 在我看来，从代码中的注释中自动生成的文档是一个理想的机制，因为：
- 交叉引用是自动pipe理的，始终全面且最新
- 文档可以（重新）从源代码生成，并与新版本随意同步
- 由于文档位于代码本身的旁边，因此可以通过自动代码风格检查程序和代码审阅程序的组合轻松进行validation。
的确，保持这些文档是最新的，需要遵守规定，但是这样做需要的努力最小化（当你改变代码时，文档就在那里，并且很容易编辑），并最大化简单文本评论的回报。
Java成功如此迅速的原因之一是通过Javadoc的核心类的一致和直观的文档。
如果您的API是正在进行的项目，那么使用协作工具（例如Wiki，论坛或邮件列表）loggingAPI，可以让您吸引最终用户，并了解他们需要支持的地方。 希望它会如此受欢迎，用户自己将开始提供支持和build立一个超越你的努力来logging项目的社区。
你在创build优秀的API文档时发现哪些工具和技术最有用？
我还没有创build任何伟大的API文档，但我已经使用了一些。
我遇到的最有价值的工具和技术是文档包括简单，实际工作和用户可以交互的完整示例。 我读过的最棒的 API文档之一就是“ Inform 7devise者手册” ，自从我上次阅读以来，它似乎已经分成了两本手册。 早期的草稿（2006）大约有700页长，包含了300多个完整的可行例子，每个例子都可以立即加载和交互。 这是学习一个非常丰富，复杂的API的惊人的帮助。
另一个我发现对学习者非常有帮助的技术是Don Knuth一贯的文档：他包括练习， 每个练习的答案都在本书的后面。
有很多实用工具可以让你编写和维护一个完整的和更新的API文档。 当然，你可以通过简单的search（doxygen，javadoc，rdoc等等）轻松find它们。然而，正如Uri指出的那样，人们只需要简洁明了，并且要使用包或API。
想到写什么，写什么，想到了我记得得到的最有用的帮助。 大多数perl模块文档都有一个“概要”部分。 这是一个真正的开始，我还没有在自动生成的API文档（例如Qt或者一些javadoc生成的Java包）中find令人惊讶的库或API。 考虑到你发现什么时，你说：
$ perldoc CGI
你知道该期待什么，你可以find一个例子：
# CGI script that creates a fill-out form # and echoes back its values. use CGI qw/:standard/; print header, start_html('A Simple Example'), h1('A Simple Example'), start_form, "What's your name? ",textfield('name'),p, "What's the combination?", p, checkbox_group(-name=>'words', -values=>['eenie','meenie','minie','moe'], -defaults=>['eenie','minie']), p, "What's your favorite color? ", popup_menu(-name=>'color', -values=>['red','green','blue','chartreuse']),p, submit, end_form, hr; if (param()) { my $name = param('name'); my $keywords = join ', ',param('words'); my $color = param('color'); print "Your name is",em(escapeHTML($name)),p, "The keywords are: ",em(escapeHTML($keywords)),p, "Your favorite color is ",em(escapeHTML($color)), hr; } print end_html;
当然，在这之后你有一个完整的API文档，注意事项，例外，规则，提示等，但是对于我来说，这个信息比API文档本身更有价值。 因为你需要更多的包的function，你当然要阅读文档，甚至当你看到示例代码做了一些你需要稍微不同的东西的时候，你就知道你需要什么API位（函数，方法等）看看可能的变化。
在API的任何元素中都有自明的命名。
这些元素的清晰简明的文档。
文档不应该作为APIdevise的结果而生成，而应根据项目启动时指定的function要求来生成。
只要文档已更新，该工具就无关紧要。
文档生成器非常适合在文档的各个部分之间创build链接 ，并检查布局等，但不能添加那些不在其中的信息。 最常见的信息是：“我为什么要这么做？”
就我而言，我使用了两个工具：
-
一个维基给你的大局。 什么地方在哪里，在哪里寻找细节。 这些东西很less改变，只是讲述devise决策并给出指示。 它很容易编辑，但大多是静态的。
-
大量的testing显示如何使用代码。 不pipe怎么说，你都需要写出来，所以要像其他代码一样写（干净可读），并把它们变成你的例子。 主要优点：文档可以说谎，错误或过时。 testing总是告诉真相（TATTT）。
永远记住：就像一行代码一样，必须保留一行文本。 更糟的是，一行文本没有编译器来检查它。 所以保持文档尽可能短（但不要短）。
我目前正在使用Sandcastle帮助文件生成器。
这是Windows的一个工具，它可以从您embedded.NET源代码的XML文档注释中生成MSDN样式的文档。
这个自动生成的内容是好的，但还不够：还需要介绍部分，介绍整个软件，说明如何安装，也许有各种用例的教程等。您可以使用SHFB创作这种types的信息：SHFB将其称为“概念性内容”，并使用“MAML”模式将其编写/标记出来。
从您编写的概念内容中，您可以轻松地将超链接编写到API参考文档的任何页面。
此外，尽pipe概念内容的内容取决于您，但它使用与API参考相同的样式表呈现为HTML：例如，如果API参考文档的页面（从代码中的注释生成）看起来像这样 ，概念内容的页面（使用MAML写的）看起来像这样 。
该工具还会生成一个目录，以帮助导航。 我主要是find足够的MSDN文档; 所以也许可以生成类似MSDN的文档的工具集也是足够的。
