标签: documentation

Sphinx是Python的新文档工具.它看起来非常好.我想知道的是:

• 这对于记录C++项目有多适合？
• 是否有任何工具可以将现有文档(例如doxygen)转换为Sphinx格式？
• 是否有使用Sphinx的C++项目的在线/可下载示例？
• 任何使用过Sphinx的人提示？

我正在尝试记录一个方法并尝试使用@link和@code在JavaDoc中一样.

我知道在kotlin有一个kDoc,但我找不到它们或至少有类似的东西.

是否有理由将两者都包括在内@version并@since作为课程的一部分？

它们似乎是相互排斥的.

此外,这是什么%I%和%G% 意味着,以及如何设置/使用它们？

 @version %I%, %G% 

谢谢

你知道<code />JSDoc中是否有某种标签吗？我需要在我的文档中添加代码片段,如下所示:

/**
 * This function does something see example below:
 *
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

我需要将注释中的代码作为代码显示在JSDoc中(如果没有突出显示语法,至少像预先格式化或具有灰色背景的东西).

只有谁有权访问源代码才能看到私有方法文档.是否值得花费在它上面的努力？

我继承了现有的API,我想用swagger记录它,但我还不知道它的全部范围.Swagger(或其他中间件/工具)可以根据现有的快速路线自动神奇地生成yaml(swagger)吗？

对于我在其他问题上看到的情况,似乎这主要是一个手工工作,但我仔细检查是否有人在这里找到了办法.

我有一个小代码库,我正在用YARD记录.当我运行yardoc命令时,它告诉我:

Files:          40
Modules:        14 (    0 undocumented)
Classes:        39 (    0 undocumented)
Constants:      21 (    4 undocumented)
Methods:       239 (   31 undocumented)
 88.82% documented

我希望它只是列出未记录的项目,而不是浏览我的所有代码来查找未记录的常量和方法.有人知道怎么做吗？

基本上,问题是:我应该在哪里(以及以何种格式)存储与我的Visual Studio项目相关的文本开发人员文档？

详细说明:XML注释很棒,但它们并不涵盖所有用例.有时,您希望在高级别描述项目的类体系结构,向库中添加使用说明,或者将任何其他类型的消息留给处理此项目的未来几代开发人员.

我想将这些文档作为文件直接添加到Visual Studio项目中,以确保(a)开发人员无需进一步搜索即可使用这些文档,以及(b)它们受版本控制(使用相同的svn/git /任何存储库)作为源代码).

目前,我_Documentation在项目中添加了一个文件夹并使用了文本文件,但我不确定这是否是最佳解决方案.Visual Studio没有自动自动换行文本¹的选项,并且在每次更改后手动修复换行符都很烦人.另一方面,Word文档在版本控制方面效果不佳,而TeX在每台开发者PC上设置和教授都太麻烦了.

有没有完善的最佳实践？

¹我知道有编辑/高级/自动换行,但这只会影响显示,而不会影响文件本身.

我有一个返回当前对象的方法,我该如何记录？

/**
 * set something
 *
 * @return this
 */
public function setSomething(){
            // ...
    return $this;
}

或者我应该做的@return self还是@return Current_Class_Name？

我正在使用ReStructuredText(ReST)格式编写一些文档,以便稍后使用Sphinx生成Web页面,我找不到编写一些"粗体斜体"文本的方法.

所谓的"强调"(斜体)和"强调"(粗体)文本都有标记.他们*italic text*和**bold text**分别.我还阅读了一些关于这种格式的文档,这些格式标记不能简单地"嵌套".即***text***(或** *text* **)不产生粗体斜体文本.

仍然可能有某种方式来生成一个用粗体和斜体标记强调的文本,因为通过这种方式标记文本片段是一种普遍的做法.