标签: documentation

从我所做的研究来看,我似乎无法找到格式化多行phpdoc @param线的正确方法.建议的方法是什么？

这是一个例子:

/**
 * Prints 'Hello World'.
 *
 * Prints out 'Hello World' directly to the output.
 * Can be used to render examples of PHPDoc.
 *
 * @param string $noun Optional. Sends a greeting to a given noun instead.
 *                     Input is converted to lowercase and capitalized.
 * @param bool   $surprise Optional. Adds an exclamation mark after the string.
 */
function helloYou( $noun = 'World', $surprise = false ) {

    $string = 'Hello ' . ucwords( strtolower( …

许多数据库系统不允许对表和字段进行注释或描述,那么除了明显具有良好命名约定外,如何记录表/字段的用途？

(我们现在假设"优秀"表和字段名称不足以记录数据库中每个表,字段和关系的完整含义.)

我知道很多人使用UML图来可视化数据库,但我很少 - 如果有的话,看到包含字段注释的UML图.但是,我在使用.sql文件内的注释方面有很好的经验.这种方法的缺点是,.sql随着数据库结构随时间的变化,它需要手动保持文件的最新状态 - 但如果这样做,您也可以将其置于版本控制之下.

我见过的其他一些技术是描述数据库结构和关系的单独文档,以及在ORM代码或其他数据库映射代码中手动维护的注释.

你过去怎么解决这个问题？存在哪些方法以及与它们相关的各种利弊？您如何在"完美世界"中解决这个问题？

更新

正如其他人所指出的那样,大多数流行的SQL引擎实际上都允许注释,这很好.奇怪的是,人们似乎并没有太多使用这些功能.至少不是我过去参与过的项目.

我发现了一些类似的问题(这里,这里,这里),询问是否将文档存储到版本控制中.我有一个更具体的要求和一般性问题.具体要求是我想使用Git.更一般的问题是,如何将文档(用于项目的设计,测试,一般实践,技巧等)存储在Git中？更广泛地说,应该存储哪些文件？

我可以想到几个方面:

1. Word/Open Office文档.新的Office Word具有docx格式,它可以压缩文档,但它也有一个解压缩的XML格式,可用于在Git中有效地存储差异.尽管如此,diff功能仍然被打破,因为XML被压缩在一条线上.这并不比将二进制文件存储到Git中更好.
2. 维基.那里存在什么分布式维基？这就像某种Latex事情,文档被编写和编译/视为维基.
3. 乳胶 - 但从用于纸张我发现它非常不适合文件.是否有相同的文档？(如何编写手册页？)
4. 纯文本格式,但由于缺少图表而缺乏这一点,这带来了另一个观点.

应该如何存储视觉效果？他们首先应该创作什么？我正在Linux环境中开发,但项目中的其他一些参与者都在Windows上.哪种跨平台解决方案类似于Visio？当然,它不应该创建存储到Git中的二进制文件.那怎么会与文件相关呢？(例如,类似于Latex在编译时可以引用其他图表.)

SELECT x FROM SomeClass
WHERE x.dateAtt BETWEEN CURRENT_DATE AND (CURRENT_DATE + 1 MONTH)

在上面的JPQL语句中,SomeClass有一个memebr dateAttr,它是一个java.util.Date并且有一个@Temporal(javax.persistence.TemporalType.DATE)注释.

我需要一种方法来做这(CURRENT_DATE + 1 MONTH)一点 - 它在当前状态下显然是错误的 - 但是找不到带有JPQL日期函数的doc.

任何人都可以指向我的文档的方向,文档JPQL日期函数(以及如何执行此特定查询)？

如果你有一个公共函数可能抛出一个异常,它使用其他(私有或公共)辅助函数也可以抛出异常,我认为你应该记录公共函数可以抛出的异常,这包括辅助函数抛出的异常.

像这样(使用Doxygen):

/** 
 * @throw Exception ...
 * @throw ExceptionThrownByHelper ...
 * @throw ExceptionThrownByHelpersHelper ...
 */
void theFunction() 
{ 
    helperWhichMayThrowException();
}

并且helperWhichMayThrowException()还调用可能抛出异常的其他函数.

为此,您可以:

1. 递归地跟随所有函数theFunction()调用并查找该函数所引发的异常.这是很多工作,当您向助手添加异常时,您可能忘记在某处记录异常.
2. 捕获助手抛出的所有异常theFunction()并转换它们,这样您就可以确定只抛出您指定的异常.但那么为什么要使用例外？
3. 不要担心辅助函数抛出的异常,但是你不能对所有异常进行单元测试,因为你不知道公共函数可以抛出哪些异常
4. 有一些工具(半)自动列出助手抛出的所有异常等.我查看了Doxygen的文档,但没有找到办法做到这一点.

我想使用选项4,但我还没有找到一个好的解决方案,也许它可以用Doxygen吗？或许我只是想要记录多少???

编辑:也许它不是很清楚,但我正在寻找一种简单的方法来记录所有异常(最好使用Doxygen)函数可能抛出而无需手动检查所有辅助函数.一种简单的方法包括"不记录所有异常"或"捕获并转换所有异常theFunction()"

从Java和Eclipse我习惯于@inheritDoc允许使用与基类/方法相同的文档.

如何在C#和Visual Studio 2010中完成类似的操作？

如何将文档字符串和/或注释作为一个整体添加到Clojure库/命名空间,即不仅仅是命名空间中的特定函数？

我注意到clojure源(comment ...)在某些地方用来做这个(例子),是推荐的吗？

我发现自己有一个用例,除了从基于Sphinx的文档源生成HTML和PDF之外,我还想生成reStructuredText源文件的Markdown版本.

我的初步研究没有在Sphinx中找到任何核心或扩展支持.除了手动使用pandoc或为任务创建新的Sphinx扩展外,是否有更简单/更集成的解决方案？

我必须记录我的API.我必须使用其中任何一个Slate或Swagger.我想知道哪一个有更多选择,优点和缺点,哪一个更好.

什么选项,以及GUI前端的位置,我是否需要设置删除段落

此类的文档是从以下文件生成的:

从我的项目文档页面？

或者,如何删除此文件列表中的绝对路径,例如C:/Users/Avesta/Desktop/CF/trunnk/CloudServer/在下面的代码段中:

？