java - 当我修改别人的代码时如何修改 Javadoc？

Question

我正在处理其他人的代码并进行重大修改。 (我正在将其转换为使用与他最初使用的数据库不同的数据库。)如何在 Javadoc 注释中表明我不是代码的原始作者，但我确实对它做出了贡献。是否已经有一种干净或标准的方式来做到这一点？我的谷歌搜索并没有帮助我解决这个问题。

例子:

/**
* This class does some really awesome stuff.
* 
* @author Steph the Great - Modified to use PostgreSQL instead of Derby;
*         added comments to the code
*/

我也不知道原作者的名字，所以只能写我自己。 . .

Answer 1

那些注释不属于 javadoc :-) javadoc 应该解释契约(Contract)——它是在自动生成的“文档”中提取和显示的内容。其余的只是普通注释，或者在这种情况下可能更好的是 SCM 日志条目，在 javadoc 中没有位置!

我可能会离开原作者，但如果你想获得荣誉......

...见 @author javadoc 引用并注意它可以包含多次。本栏目explicitly relates to multiple authors和订购等。

/**
* This class does some really awesome stuff.
* It uses PostreSQL. 
*
* @author Steph the Great
* @author Freddy Four Fingers
*/
// DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }

编码愉快。

---

关于与帖子中的示例有些无关的问题的注释...如果不知道作者，那么可以做几件事。首先添加一个链接或对原始来源的引用——为了清楚起见，还可以注明可选的“我最初没有写这个”。

然后，根据您的喜好:

1. 不要指定 @author 字段——甚至你自己也不要。 这不是必需的。
2. 将自己添加为唯一作者；上面的javadoc中提到了原始来源
3. 添加一个虚拟作者和你自己作为第二作者，例如@author Unknown @author 未注明(见评论和 @author)。
4. 在许可条款内做任何你想做的事(如果有的话)。