当我修改别人的代码时,如何修改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应该解释合同 - 它是在自动生成的"文档"中提取和显示的内容.其余的只是正常的评论,或者在这种情况下,SCM日志条目可能更好,并且在javadoc中没有位置!

我可能会离开原作者,但如果你想要信用......

...请参阅@author javadoc参考,并注意它可以多次包含.本节明确涉及多位作者和订购等.

/**
* 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 unascribed(见评论和@author).
4. 如果有的话,在许可条款中做任何你想做的事.

Answer 2

您可以拥有多个@author标签.因此,如果您对某个类进行了大量更改,只需添加一个@author包含您自己名称的新标记即可.没有必要列出你所做的改变 - 修订历史应该足够好.