如何记录 AngularJS + Ruby on Rails 应用程序？ [关闭]答案

【问题标题】：How to document AngularJS + Ruby on Rails app? [closed]如何记录 AngularJS + Ruby on Rails 应用程序？ [关闭]
【发布时间】：2015-08-02 16:59:12
【问题描述】：

我正在使用 yard 从 rdoc 文件生成 Rails 应用程序的文档。有 AngularJS 文档生成器，但如何将它们连接起来为 AngularJS + Rails 应用程序生成一个连贯的文档？

【问题讨论】：

但是为什么你的文档应该是“连贯的”？您需要 Rails 对应的 API 文档和 Angular 的源文档。我错过了什么吗？
在 Angular 文档中引用相关的 Rails 模型和方法会很有用，反之亦然。
这不是打破松耦合原则吗？你应该有尽可能少的依赖，你的 Angular 应用应该依赖 http apis 而不是直接依赖 Rails 应用我相信
也许吧，但盲目地到处应用它也许是完全错误的？如果我正在编写一个由 Angular 前端和 Rails 后端组成的应用程序，那么拥有一个有助于以最少的努力记录两者的系统（或至少一组精确的规则）对我来说会更有用。我想其他后端或前端的潜在作者以一种很好的方式记录两者的耦合可能是有益的。
两年后回顾这个问题，我的方法似乎得到了一些理由，尽管我无法准确地定义我想要什么。看来我所追求的是swagger 之类的东西，这不仅仅是文档问题，而是设计原则之一。

标签： ruby-on-rails angularjs documentation rdoc yard

【解决方案1】：

在这种情况下，将它们分开可能很好，而且将它们分开确实可能更有意义。 Angular 将仅用于您的客户端内容，我假设您随后将 Rails 用作 API，或者可能是应用程序功能的不同部分。无论哪种方式，它们基本上都在做不同的事情，因此将它们放在不同的文档部分是有意义的。

如果您愿意，可以为您的文档创建一个“登录页面”：一个按钮链接到 Angular 文档，一个按钮链接到 Rails 文档，这样就可以解决将它们都“放在一个地方”的需要。实际上，想办法让它们在同一个系统中重叠可能并不值得，而且实际上可能会降低用户体验。

【讨论】：

从前端和后端的未来维护者的角度来看，这很好。但是，在项目开始时拥有单一的文档来源会显着提高生产力。

【解决方案2】：

正如前面的回答所说，最好使用两种不同的工具并将它们链接在一起。

我会从 Apipie 之类的东西开始，或者只是 rdoc 来记录 ruby 内容。另外，我会寻找一个好的 js 文档生成器。 This article 比较了四个不同的生成器，而 'Docco' 似乎有一个名为 'Rocco' 的 ruby 端口，它甚至可以为 ruby 和 js 生成文档。另一方面，JSDoc 使您能够将自定义页面集成到您的文档中（在这里您可以放置指向 apipie 生成器的链接）。

一般来说，我可能会选择 Rails API 文档，并有一些约定来评论你的 Angular 代码，因为 Angular 的东西可能没有你系统的其他部分可以访问的 API，因此只需要一些内部文档。

【讨论】：