Questions tagged «documentation-generation»

行为驱动的开发及其标志性的“ Given-When-Then”场景语法最近被大肆宣传，因为它有可能用作软件功能评估的边界对象。 我绝对同意，Gherkin或您喜欢的任何功能定义脚本都是商业可读的 DSL，并且已经提供了这样的价值。 但是，我不同意它是非程序员可写的（就像Martin Fowler一样）。 有人对非程序员编写的场景，然后由开发人员提供的场景有说明吗？ 如果确实对缺乏可写性达成了共识，那么您是否会看到一种工具的问题，该工具可以从实际测试中生成业务可读的场景，而不是从场景开始并对其进行检测。 更新：关于“场景生成器”工具，它当然不会神奇地猜测业务语言;）但是，就像我们当前使用正则表达式匹配器以自顶向下的方法（在抽象维度上）创建测试一样，我们可以使用字符串构建器以自下而上的方式创建方案。 “仅给出想法”示例： Given I am on page ${test.currentPage.name} And I click on element ${test.currentAction.element} …

24 documentation  bdd  documentation-generation  business-rules 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 去年关闭。 我想记录我的代码，以使几个月后再次阅读和浏览代码的需求降至最低。 我知道有不同类型的文档（在源代码中和外部，序列图等中）。 我只想知道什么是记录我的代码的有效方法，所以几个月后我想看我的代码时，我花更少的时间在阅读代码和理解代码流上。

22 documentation  code-reviews  documentation-generation  help-documentation 

所以我们有一个像这样的界面 /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } 最近，我们播放了一个文档故事，涉及生成并确保像上面那样有大量XML文档。但是，这导致了很多重复的文档。示例实现： /// <summary> /// A Foo Creator which is fast /// </summary> …

20 c#  documentation  xml  documentation-generation 

我目前正在使用两个系统编写代码文档（上午使用C ++）： 使用Doxygen格式在代码旁边添加有关方法和类成员的文档。在服务器上，Doxygen在源上运行，因此可以在Web浏览器中看到输出 概述页面（描述一组类，应用程序的结构，示例代码等）被添加到Wiki中。 我个人认为这种方法很简单，因为有关成员和类的文档确实与代码接近，而概述页面确实很容易在Wiki中进行编辑（并且还很容易添加图像，表格等）。Web浏览器允许您查看两个文档。 我的同事现在建议将所有内容都放入Doxygen，因为我们可以创建一个包含所有内容的大帮助文件（使用Microsoft的HTML WorkShop或Qt Assistant）。我担心的是，编辑Doxygen样式的文档要困难得多（与Wiki相比），尤其是当您想要添加表，图像等时（或者Doxygen的“预览”工具不需要您生成）代码才能看到结果？） 大型开源（或封闭源）项目使用什么来编写其代码文档？他们还将Doxygen样式和Wiki分开吗？还是他们使用其他系统？ 公开文档的最合适方法是什么？通过Web服务器/浏览器，还是通过大的（几个100MB）帮助文件？ 在编写代码文档时，您采用哪种方法？

13 documentation  documentation-generation  wiki 

是否有一个与“不赞成使用”相似但又不同的好术语，表示方法或API已存在于代码库中，但由于其实现不完整或可能会发生变化而不应使用？（是的，我知道，这些方法不应该公开，yada yada yada。我没有创造自己的情况，我只是想尽力而为。） 人们有什么建议？实验性的，不完整的，还有其他吗？ 如果我正在为该API构建仍在不断变化的javadoc文档，那么我应该使用@deprecated标记还是有更好的约定？对我而言，@ preprecated表示此API很旧，可以使用更新的首选机制。在我的情况下，别无选择，但是API中的某些方法尚未完成，因此不应使用。目前，我无法将其设为私有，但我想在文档中添加明确的警告。

12 documentation  terminology  api  documentation-generation  javadocs 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 4年前关闭。 我已经完成了一个Web应用程序，该应用程序基本上是用PHP开发的，它只是另一个常规的Web应用程序。通常，当我交付最终产品版本时，我只是将代码文档和体系结构信息移交给客户端。但是，对于这个特定项目，客户坚持要拥有有关该项目的完整的输入和输出数据。 所以我只是想知道...除了代码和体系结构文档之外，我还可以为客户提供哪些强制性技术文档和非技术文档？ （也可以向客户介绍有关该项目的各种统计数据和数据，这样他才能真正知道所涉及的工作量以及产品的实际效果如何。）

11 project-management  documentation  documentation-generation  projects-and-solutions 

我已经为记录了代码doxygen，但是我不希望它提供默认的HTML。我知道我可以通过提供自定义CSS，页眉，页脚等（如GNOME一样）以及如何向文件中添加通用PHP代码并将其保存为来对其进行自定义.php，但这并不是我真正想要的。 我想要的是像MSDN这样的输出。我真的无法形容。我的问题是，使用doxygen和模板之类的东西是否有可能，还是我必须输出XML并用另一个程序解析（我不介意编写）？

10 documentation  templates  documentation-generation