Неполный Javadoc в Java 8?

Question

Является ли Javadocs для Java 8 незавершенным?

Некоторые из комментариев методы опущены и описание метода копируется (неправильно) от базового класса (например, java.util.IntSummaryStatistics toString() метода с пометкой «Описание копируется из класса: Object».

public String toString()

Описание скопировано из класса:. Object

возвращает строковое представление объекта в общем, метод toString возвращает строку, "textually представляет" этот объект. Результат должен быть кратким , но информативным представлением, которое легко прочитать человеку. В нем рекомендуется, чтобы все подклассы переопределили этот метод.

toString метод класса Object возвращает строку, состоящую из имени класса которого объект является экземпляр, на-знак символ «@», и без знака шестнадцатеричное представление хэш-кода объект. Другими словами, этот метод возвращает строку, равную значению:

getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:

toString в классе Object

Возвращает:

строковое представление объекта.

Фактический toString метод возвращает класс конкретной информации, как это:

IntSummaryStatistics{count=10, sum=129, min=2, average=12.900000, max=29} 

, а не по умолчанию, унаследованные от класса Object, как показано here.

Answer 1

Да, здесь есть пара различных проблем.

У спецификации IntSummaryStatistics.toString есть текст, скопированный с Object.toString, который он переопределяет. Первая часть верна:

Возвращает строковое представление объекта. В общем случае метод toString возвращает строку, которая «текстово представляет» этот объект. Результат должен быть кратким, но информативным представлением, которое легко читать человеку. Рекомендуется, чтобы все подклассы перекрывали этот метод.

Это представляет контракта, что Object.toString определяет и что накладывает требования на все подклассы.

Вторая часть спецификации копируется из Object.toString заключается в следующем:

Метод toString для класса Object возвращает строку, состоящую из имени класса которого объект является экземпляром, на-знак символ '@' и шестнадцатеричное представление без знака хеш-кода объекта. Другими словами, этот метод возвращает строку, равную значению:

getClass().getName() + '@' + Integer.toHexString(hashCode())

Это правильно, но не имеет значения, так как это говорит о реализации Object.toString в спецификации IntSummaryStatistics.toString. Здесь нецелесообразно копировать. Заметим, что речь идет о реализации от Object.toString, а не о договоре 0, что переопределения необходимы для реализации.

Проблема заключается в том, что директива javadoc {@inheritDoc}, которая используется в комментарии к doc для IntSummaryStatistics.toString, копирует все это, когда это действительно необходимо только для копирования ее части. Конкретно, контракт, наложенный на подклассы, должен быть скопирован, но спецификации реализации не должно быть.

До JDK 8 не было возможности отделить их, поэтому текст был либо скопирован вручную (что привело к его противоречивости), либо использовалось {@inheritDoc}, которое копирует нежелательные материалы. В JDK 8 были введены некоторые новые теги javadoc, такие как @implSpec (спецификация реализации), которые разделяют комментарий к документу в разные разделы. Директива {@inheritDoc} может выборочно наследовать эти разделы, а не наследовать всю документацию. К сожалению, эти теги не использовались в этом случае, поэтому у нас есть некоторые возможности для очистки.

Новые теги задокументированы в этом informational JEP. Обратите внимание, что эти теги специфичны для JDK и не могут (пока) использоваться для javadoc вне JDK.

Там еще одна часть отсутствует. Комментарий к документу Object.toString концептуально разделен на часть, определяющую контракт по подклассам, и часть, определяющую ее реализацию. В идеале мы хотели бы, чтобы часть контракта была скопирована в документацию IntSummaryStatistics.toString, и там будет другой раздел, который определяет реализацию IntSummaryStatistics.toString. Оказывается, есть, но это не видно!Исходный код для IntSummaryStatistics.toString имеет это в качестве дока комментария:

@Override 
/** 
* {@inheritDoc} 
* 
* Returns a non-empty string representation of this object suitable for 
* debugging. The exact presentation format is unspecified and may vary 
* between implementations and versions. 
*/ 
public String toString() { ... 

К сожалению, текст «Возвращает непустое строковое представление ...» не появляется на выходе JavaDoc. Мне кажется, что это еще одна ошибка. EDIT: ошибка заключается в том, что комментарий находится между аннотацией @Override и остальной частью декларации метода. Комментарий к документу должен быть отправлен до всей декларации метода, включая аннотации. Таким образом, комментарий выглядит как комментарий к документу, но поскольку он не в том месте, он игнорируется javadoc.

Я подал JDK-8080449 и JDK-8080450 для покрытия этих вопросов.

Answer 2

Я бы сказал, что вы правы, что здесь что-то не так. Этот метод toString() задокументирован на странице javadoc IntSummaryStatistics. Он не упоминается в ссылке «Методы, полученные из класса Object». Поэтому я бы сказал, что если этот метод отличается от Object.toString(), то поведение должно быть документировано.

Answer 3

Я не согласен называть это «неправильным». Но в первую очередь это вводит в заблуждение относительно того, как класс Object реализует toString(), потому что реализация на самом деле отличается от этого.

Эта часть не должна быть скопирована, на мой взгляд. Это вводит в заблуждение и не добавляет доступной информации.

Но я полностью согласен с тем, что форма формы документации несколько «неверна» и недостойна для такого публичного API. Даже никакая документация не была бы лучше, чем эта документация.