在代码文档方面,通常认为代码应该自行解释,内联代码文档(不包括公共API文档)应该只解释元代码问题,例如变通方法,为什么选择特定实现的解释等等.
如何使您的代码更具可读性并更多地解释自己？
我目前正在开始使用doxygen来记录我的源代码.我注意到语法非常繁重,每次我修改源代码时,我还需要更改注释,我真的有这样的印象,即在源代码中为每个更改修改注释时要花太多时间.
您是否有一些技巧可以有效地记录我的源代码？
是否存在doxygen执行以下操作的某些编辑器(或现有编辑器的插件)？
PS:我正在开发一个C/C++项目.
我们都有记录代码的好习惯,对吧？
如今,代码内文档本身就有一种语法.它几乎就像一种编程语言.问题是:
很难不听说doxygen.在我参与的每个开源软件项目中都提到过.但是,看看官方的doxygen网站,doxygen定义任何规格都是显而易见的! 当我读到"它可以帮助我的方式"时,我得到的印象是,doxygen只是一个提取代码内文档并将其呈现在漂亮的HTML页面中的软件.看看doxygen首页,我甚至认为doxygen可以使用第三方规范中定义的任何文档语法并将其解压缩并输出为HTML.
而且,有趣的是,doxygen的网站,并没有利用这个词doxygen的,就好像它是没有品牌的软件,而是一个普通名词(当然,是吗？)
什么是doxygen真的吗？
我对doxygen和其他代码解析器之间的关系特别感到困惑,比如ANTLR,boost-spirit,Ragel ......
例如,什么是doxygen可以做的,ANTLR不能,而ANTLR可以做氧吗？
另外,看看Drupal项目.他们有:
因此,采用C++类比,似乎"doxygen"这个词过载并且在不同的上下文中意味着不同的东西.
在Drupal项目中,"doxygen"并不是指软件,而是指文档语法的(标准？)规范,尽管如上所述,doxygen网站本身的头版并未声称是这样的事情!
所以,我的离题是:
还有其他文档语法规范吗？
c++ documentation specifications doxygen documentation-generation
Joshua Bloch在他的Effective Java中写道:
"使用Javadoc @throws标记来记录方法可以抛出的每个未经检查的异常,但不要使用throws关键字在方法声明中包含未经检查的异常."
嗯,这听起来确实合理,但如何找出,我的方法可以抛出什么未经检查的异常？
让我们想一下以下课程:
public class FooClass {
private MyClass[] myClass;
/**
* Creates new FooClass
*/
public FooClass() {
// code omitted
// do something with myClass
}
/**
* Performs foo operation.<br />
* Whatever is calculated.
* @param index Index of a desired element
* @throws HorribleException When something horrible happens during computation
*/
public void foo(int index) {
try {
myClass[index].doComputation();
} catch (MyComputationException e) {
System.out.println("Something horrible happened during computation");
throw new …如何记录phpDoc的类常量？我已经阅读了手册,但我找不到任何关于它们的信息.
最近,我们的团队正在使用node.js开发一个新项目.开始使用node.js并不困难.但是现在我们都开始使用这种新技术,并且在这种基于事件的开发方面缺乏经验.
所以我想知道是否有任何书籍,博客或其他材料涵盖了node.js的"最佳实践"主题,就像"有效的c ++","有效的java"等.
我注意到Clojure多行文档字符串似乎在大多数情况下都是手动格式化的,包括clojure.core中的那些.示例来自https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj:
(defn flatten
"Takes any nested combination of sequential things (lists, vectors,
etc.) and returns their contents as a single, flat sequence.
(flatten nil) returns an empty sequence."
{:added "1.2"
:static true}
[x]
(filter (complement sequential?)
(rest (tree-seq sequential? seq x))))
这看起来很奇怪,因为它意味着不同的文档字符串将具有不同的换行长度等,需要手动维护.
有没有更好的方法来格式化多行文档字符串？
在更新到roxygen2版本6.0.0 之前,似乎使用@export不在包中函数头底部的标记支持的包.例如:
#' Title
#' @param foo
#' @return bar
#'
#' @export
#'
#' @seealso Other blah blah
roxygen2使用我的roxygen25.0.1版安装时,上面的代码将成功构建并正确填写命名空间.但是,随着更新,这种形式的文档将无法正常工作,并将roxygen2其从NAMESPACE.R中主动删除.
我可以通过移动@export到底部来解决这个问题
#' Title
#' @param foo
#' @return bar
#'
#' @seealso Other blah blah
#' @export
我的问题是这个问题是否出现在设计中？我在发行说明中看不到任何指定@export更改的内容:https://github.com/klutometis/roxygen/releases/tag/v6.0.0
这roxygen2是不是应该如何工作和操作直到这一点是无意的？或者这是故意的改变？
NB显然,对于不同版本制作一个完整的mwe是困难的,任何关于如何解决这种欢迎的建议
编辑:经过进一步测试后,我开始怀疑除此之外还有更多的东西.我正在使用rstudio中的构建和文档快捷方式,我最近也更新了,甚至退回到roxygen25.0.1版本也阻止我重建过去工作的旧函数的文档.
有没有人知道任何软件需求的示例和模板的来源,构建环境描述和软件开发常见的其他类型的文档？
谢谢!
我已经开发了一个非常优秀的API,我在Postman上有它,它非常好用.现在我必须生成一个html文档,以便将其与我的源代码一起保存在/ docs中.
有没有工具或方法来实现这一目标？我真的不想写所有这些文档.分享邮递员收藏不是一种选择.