如何记录 AngularJS + Ruby on Rails 应用程序？

Question

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

- helcim

---

但是为什么你的文档应该是“连贯的”呢？你需要Rails对应的API文档，以及Angular的源代码文档。我有什么遗漏吗？ - EugZol

在 Angular 文档和 Rails 模型/方法之间相互引用会非常有用。 - helcim

这不违反了松耦合原则吗？你应该尽可能减少依赖，你的Angular应用程序应该依赖于HTTP API而不是直接依赖于Rails应用程序。我认为。 - Francesco Belladonna

也许，但是盲目地到处应用可能是错误的吗？如果我正在编写一个由Angular前端和Rails后端组成的应用程序，那么对我来说，拥有一个系统（或至少一个精确的规则集）可以帮助我以最小的努力记录两者将更加有用。我想这可能对其他后端或前端的潜在作者有益，他们可以以良好的方式记录两者之间的耦合。 - helcim

回顾两年前的这个问题，我的方法似乎得到了一些证明，尽管我无法准确地定义我想要什么。看起来我追求的是类似于 swagger 的东西，这不仅仅是文档的问题，而是设计原则的问题。 - helcim

Answer 1

在这种情况下，将它们分开可能是可以接受的，并且将它们分开可能更有意义。Angular仅用于您的客户端内容，我假设您正在使用Rails作为API或应用程序功能的其他部分。无论哪种方式，它们都在根本上执行不同的任务，因此将它们放在不同的文档部分中是有意义的。

如果您想要，可以为文档创建一个“登陆页面”：一个按钮链接到Angular文档，一个链接到Rails文档，这将解决将它们放在“一个地方”的需求。实际上，想出一种使它们在同一个系统中重叠的方法可能不值得努力，并且实际上可能会导致更糟糕的用户体验。

- Tyler

---

从前端和后端未来维护者的角度来看，这是可以接受的。然而，在作为小型单人开发项目启动的项目中，拥有单一的文档来源会更加高效。 - helcim

Answer 2

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

我建议从像Apipie或者只是rdoc来记录ruby的东西。此外，我会搜索一个好的js文档生成器。这篇文章比较了四种不同的生成器，而'Docco'似乎有一个称为'Rocco'的ruby端口，甚至可以为ruby和js生成文档。另一方面，JSDoc使您能够将自定义页面集成到文档中（在这里，您可以放置到apipie生成器的链接）。

一般来说，我可能只会去rails API文档，并采用一些约定来评论您的angular代码，因为angular的内容可能没有API可以被系统的其他部分访问，因此只需要一些内部文档。

- smallbutton