Как мне изменить Javadoc, когда я изменяю чужой код? - PullRequest
Новая
       2

Как мне изменить Javadoc, когда я изменяю чужой код?

31 голосов
/ 17 июня 2011

Я работаю над чужим кодом и делаю значительные изменения.(Я конвертирую его, чтобы использовать базу данных, отличную от той, которую он использовал изначально.) Как я могу указать в комментариях Javadoc, что я не являюсь первоначальным автором кода, но что я внес в него свой вклад.Есть ли чистый или стандартный способ сделать это уже?Мой поиск в Google не помогает мне разобраться в этом.

Пример: 

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

Я также не знаю имени автора оригинала, поэтому все, что я могу отрицать, это я сам.,.

Ответы [ 2 ]

33 голосов
/ 17 июня 2011

Эти комментарии не относятся к javadoc :-) Javadoc должен объяснить контракт - это то, что извлекается и отображается в автоматически сгенерированной «документации». Остальные - просто обычные комментарии или, возможно, еще лучше в этом случае, записи в журнале SCM, и их нет в javadoc!

Скорее всего, я бы просто оставил оригинального автора, но если вы хотите кредит ...

... см. Ссылку на javadoc @ author и обратите внимание, что она может быть включена несколько раз. Этот раздел явно относится к нескольким авторам и порядку и т. Д. 

/**
* 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. Делайте все, что хотите в рамках лицензии, если таковые имеются.
10 голосов
/ 17 июня 2011

Вы можете иметь более одного тега @author. Итак, если вы внесли в класс обширные изменения, просто добавьте новый тег @author с вашим собственным именем. Нет необходимости перечислять внесенные вами изменения - история изменений должна показывать это достаточно хорошо.

...