标签: documentation-generation

Objective C是否有类似于JavaDoc的文档框架,可以从源代码生成文档？

我正在寻找C#的XML源代码文档的替代方案,该文档根据XML的本质介绍了很多噪声,这些噪声在眼睛上很重要并且需要编写更多工作:

/// <summary>
/// This is text of importance. Linking to
/// <see cref="AnotherClass>is somewhat verbose.</see>
/// </summary>
/// <param name="andSo">is parameter documentation</param>

相反,我想使用Markdown作为文档:

/// This is text of importance. Linking to [an](OtherClass) is less verbose.
/// 
/// Empty lines would make a new paragraph
///
/// aParameter
/// :    could possibly be documented in definition-list manner
///      as in http://bit.ly/1l9ik26

我敢打赌我之前在Stackoverflow上找到了一个问题和答案.不幸的是我不能再找到它了.我尝试了所有可以想象的搜索关键字变体而没有运气.所以我希望你们中的任何人都能找到副本.至少我的问题将通过为现有问答提供不同措辞的"代理"来增加一些价值,从而提高未来访问者查找信息的几率.

更新:

我想我终于通过使用不同的搜索引擎找到了另一个问题:Markdown用于自动生成doc？.似乎Doxygen支持Markdown.Doxygen也支持C#.但对于@Sam Harwell提到的要求,这可能不会有很长的路要走.

这真的只是重新询问有关Visual Studio 2008的问题.VS2010是否提供任何功能来摆脱自动生成代码的CS1591编译器警告？

CS1591: Missing XML comment for publicly visible type or member

引用VS2008的问题:

这不仅仅是一个问题,而是一个烦恼.我的项目包含许多自动生成的文件(使用mgmtclassgen.exe).当我生成XML文档时,我精美评论的库受到来自这些autogen文件的xml文档警告的困扰.

有没有办法a)抑制生成这些文件的文档或b)抑制警告CS1591只是为了一组文件？我显然不想修改自动生成的文件,即使只是添加抑制编译指示.

编辑:在我的情况下,违规文件由WCF RIA服务生成,因此生成错误的文件是自动生成的WebContext类(MyProject.BusinessApplication.Web.g.cs).

我无法手动修改此文件,因为它是动态生成的,所有更改都将被删除.我也不想全局禁用警告,因为它对我的非自动生成的代码很有帮助.

我需要为我的JSF应用程序绘制一个项目文档的类图.所以我有很多类作为托管bean,因此有许多属性,因此有许多getter和setter.

当我绘制类图时,我是否还应该在图中包含getter和setter,或者我可以简单地保留它们？

虽然与这个关于在数学和学术界之外使用的LaTeX的问题有关,但我特别想知道是否有人使用或熟悉使用LaTeX生成与软件相关的任何类型文档的任何人.如果是这样,你能否说你是否喜欢LaTeX以及你使用它的目的？谢谢.

这是关于Sphinx的先前问题的通用版本.

有没有办法递归自动记录包含其中的类和函数的模块或包？

我认为为每个函数添加autofunctionor automodule指令是愚蠢的; 必须有一种方法来自动化该过程,否则我根本没有看到使用Sphinx的重点.

澄清: 而不是:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. automethod:: Seg.method_1

        .. automethod:: Seg.method_2

        .. automethod:: Seg.method_3

        .......

        .. automethod:: Seg.method_n

这需要我手动剪切并粘贴所有方法名称并相应地更新文档,我想要一个如下命令:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. MAGIC COMMAND: Automatically print the docstrings and signatures 
           of all Seg() methods.

寻找工具(windows平台)从现有的Oracle数据库中生成ER图(或类似的).
有哪些好的工具可以免费使用或成本低廉？

我已经使用GitHub页面为我的项目生成一个漂亮的网站(这个).现在我想保持我的项目文档是最新的,并且在一个README.md文件中包含所有内容可能无法扩展到我们添加的许多功能.

所以,我认为保存文档的最佳位置是GitHub wiki,但我想将wiki集成到gh-pages生成的站点,保持漂亮的布局.

我如何使用GitHub wiki并生成具有可自定义布局的HTML网站？

谷歌拥有所有api的统一文档.我想知道它使用什么文档生成器,它是否可供公众使用.它具有良好的TOC和其他功能.代码也显得整洁.

任何人都可以对此有所了解吗？

我为我的小项目创建了一个精彩的GitHub Pages 网站,并在gh-pages分支中添加了一些其他页面.我的问题是,每次我从'Settings => Automatic Page Generator'重新生成网站时,一切都被清理干净,我必须手动恢复文件.

有没有办法预防或解决这个问题？

如果自动生成器只是覆盖他的东西而不删除现有文件会好得多.