修改别人的代码时如何修改Javadoc？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/6380012/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How do I modify the Javadoc when I modify someone else's code?
提问by Steph
I am working on someone else's code and making significant modifications. (I am converting it to use a different database than the one he originally used.) How do I indicate in the Javadoc comments that I am not the original author of the code, but that I did make contributions to it. Is there a clean or standard way of doing this already? My Googling is not helping me figure this out.
我正在处理其他人的代码并进行重大修改。（我将它转换为使用与他最初使用的数据库不同的数据库。）我如何在 Javadoc 注释中指出我不是代码的原始作者，但我确实对它做出了贡献。是否已经有一种干净或标准的方法来做到这一点？我的谷歌搜索并没有帮助我解决这个问题。
Example:
例子：
/**
* This class does some really awesome stuff.
*
* @author Steph the Great - Modified to use PostgreSQL instead of Derby;
* added comments to the code
*/
I also don't know the original author's name, so all I can put down is myself . . .
我也不知道原作者的名字，所以我只能放下我自己。. .
采纳答案by Chris Jester-Young
Those comments do not belong in the javadoc:-) The javadoc should explain the contract -- it is what is extracted and displayed in the auto-generated "documentation". The rest are just normal comments or, perhaps better yet in this case, SCM log entries and have no place in the javadoc!
这些注释不属于 javadoc:-) javadoc 应该解释合同——它是在自动生成的“文档”中提取和显示的内容。其余的只是普通的注释，或者在这种情况下可能更好，SCM 日志条目并且在 javadoc 中没有位置！
I would likely just leave the original author, but if you want credit...
我可能会离开原作者，但如果你想要信用......
...see the @authorjavadoc reference and note that it can be included multiple times. This section explicitly relates to multiple authorsand ordering, etc.
...请参阅@authorjavadoc 参考并注意它可以被多次包含。本节明确涉及多个作者和排序等。
/**
* 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 { ... }
Happy coding.
快乐编码。
Notes on question somewhat unrelated to example in post... if the author isn't known, then several things can be done. First and foremost add a link or reference to where the original source was obtained-- an optional "I didn't write this originally" for clarity can be noted as well.
关于问题的注释与帖子中的示例有些无关......如果作者不知道，那么可以做几件事。首先，最重要的是添加一个链接或引用，以获取原始来源的位置——为了清楚起见，还可以注明可选的“我最初没有写这个”。
Then, depending upon your preference:
然后，根据您的喜好：
- Don't specifyan
@authorfield -- not even yourself. It's not required. - Add yourself as the sole author; the original source is mentioned above in the javadoc
- Add a dummy author and yourself as the second author, e.g.
@author Unknown@author unascribed(see comments and @author). - Do whatever you want within terms of the license, if any.
- 不要指定一个
@author字段——甚至不是你自己。这不是必需的。 - 将您自己添加为唯一作者；原始来源在上面的javadoc中提到
- 添加一个虚拟作者和你自己作为第二作者，例如
@author Unknown@author unascribed（见评论和@author）。 - 在许可条款内做任何你想做的事情，如果有的话。
回答by Chris Jester-Young
You can have more than one @authortag. So, if you've made extensive changes to a class, just add a new @authortag with your own name in it. There's no need to list the changes you've done---the revision history should show that well enough.
您可以拥有多个@author标签。因此，如果您对类进行了大量更改，只需在其中添加一个@author带有您自己名称的新标签即可。没有必要列出您所做的更改——修订历史应该足够好地显示出来。
