Как изменить Javadoc при изменении кода другого?

Я работаю над кодом другого пользователя и вношу значительные изменения. (Я конвертирую его, чтобы использовать другую базу данных, чем та, которую он изначально использовал.) Как указать в комментариях 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
*/

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

Ответы

Ответ 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 { ... }

Счастливое кодирование.

Заметки по вопросу, несколько не связанные с примером в сообщении... если автор неизвестен, то можно сделать несколько вещей. Прежде всего, добавьте ссылку или ссылку на исходный исходный код - необязательный вариант "Я не писал это изначально" для ясности также можно отметить.

Затем, в зависимости от ваших предпочтений:

  • Не указывайте поле @author - даже сами. Это не требуется.
  • Добавьте себя как единственного автора; исходный источник упоминается выше в javadoc
  • Добавьте фиктивного автора и себя как второго автора, например. @author Unknown @author unascribed (см. комментарии и @author).
  • Делайте все, что захотите, в рамках лицензии, если таковая имеется.

Ответ 2

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