Почему Javadoc не заставляет мои подклассы наследовать документацию от классов Java?

Я искал ответ в течение нескольких месяцев, и я попробовал несколько вещей, включая разархивирование папки Compressed src.zip и использование ее в качестве параметра для Javadoc (например: javadoc -sourcepath src com.example.test)

Это Javadoc по умолчанию, который поставляется с JDK 6 Update 24.

Допустим, я работаю над новой картой, которая реализует java.util.Map интерфейс. По умолчанию методы, которые я переопределяю из интерфейса Map, должны наследовать документацию от интерфейса, если я не ошибаюсь. Тем не менее, Javadoc никогда не делает это.

Единственная вещь, которая до сих пор решала эту проблему, это на самом деле создание классов, написанных на Java (например: javadoc com.example.text java.util). Я не хочу этого делать, потому что мне кажется, что я переписал классы Java, но это единственный способ сделать это? Если бы это было так, я полагаю, я мог бы просто жить с этим, но я понимал, что был другой способ сделать это.

Спасибо =) Извините, если это немного грязно. Это мой первый раз, когда я использую Stack Overflow. Мне также жаль, если этот вопрос уже задавался. Я прочитал много похожих вопросов, поскольку они не охватывают всего, что я хотел спросить, и я нашел их очень запутанными, потому что они включают в себя написание вашей собственной реализации Javadoc. В любом случае, спасибо заранее! =)

Изменить: 25 мая в 4:44

Хорошо =) Если я правильно понял, вы хотели бы увидеть пример. Это более простой пример, который я пытался увидеть, потому что я пытался что-то, что не должно работать.

package com.example;

/**
 * A simple class that returns an upper-case string representation.
 */
public class UpperCaseObject {

    @Override public int hashCode() {
        return super.hashcode();
    }

    /**
     * {@inheritDoc}
     *
     * <P>The {@code toString} method for class {@code UpperCaseObject} returns
     * converted to uppercase.</P>
     *
     * @see String#toUpperCase()
     */
    @Override public String toString() {
        return super.toString().toUpperCase();
    }

}

Я переместил этот пример (имя файла UpperCaseObject.java) в каталог javadoc-test/com/example и я также сделал еще один каталог javadoc-test/java/langразмещение Object.java (из src.zip) в нем.

Звонок на Javadoc, который я сделал, был javadoc -link http://download.oracle.com/javase/6/docs/api/ com.example из каталога javadoc-test, У меня есть каталог bin JDK6 в моем параметре пути.

Две вещи, которые я ожидал, были для UpperCaseObject.hashCode унаследовать всю документацию, и UpperCaseObject.toString все до дополнительного абзаца от java.lang.Object, Однако, к сожалению, я не получил никакой документации.

Редактировать:

Что ж, я должен был сделать следующее. Это просто обходной путь.

  1. Я скопировал все исходные файлы из source.zip, как вы это обычно делаете.
  2. Я также сделал файлы пакета для каждого пакета. Они содержат самый первый абзац (тот, что содержит сводку) и второй абзац, который гласит: "См. Сводку пакета в Java™ Platform, Standard Edition 6 API Specification для получения дополнительной информации".
  3. Исходные файлы были, по сути, суперклассами, их суперклассами (и интерфейсами) и любыми исключениями, которые они генерировали, которые также были в том же пакете. Единственным исключением был java.lang, где мне нужно было только получить Object. Исключения также были необходимы, потому что за исключением java.lang, другие пакеты не связывались, если исключение находилось в том же пакете, что и класс throwing.
  4. Я сделал javadoc все пакеты, из которых я использовал / subclassing / throwing-исключение.
  5. Я обязательно включу некоторую информацию о стандартных пакетах и ​​моем собственном пакете в файл обзора.

К сожалению, я могу пока только обойтись, но я убежден, что это может быть проблемой с моей версией Java. Похоже, что у других людей была похожая проблема, и они нашли свои обходные пути. Это только мое =)

Я все еще буду принимать ответы, но пока это самый удобный вариант. Большое спасибо!

Источник

2 ответа

Исходный файл для унаследованного метода должен быть в -sourcepath инструмента javadoc при его запуске. Вам не нужно передавать унаследованный класс в командной строке.

Источник

Одна вещь, которую вы можете сделать, это ссылка на официальный Javadoc для этих классов, используя -link опция:

javadoc -sourcepath src -link http://download.oracle.com/javase/6/docs/api com.example.test

Это позволит Javadoc обрабатывать классы SDK как "классы с внешними ссылками". Из документации Javadoc:

Классы, на которые ссылаются, чья документация не генерируется во время выполнения Javadoc. Другими словами, эти классы не передаются в инструмент Javadoc в командной строке. Ссылки в сгенерированной документации на эти классы называются внешними ссылками или внешними ссылками. Например, если вы запускаете инструмент Javadoc только для пакета java.awt, то любой класс в java.lang, такой как Object, является классом с внешней ссылкой. Внешние ссылочные классы могут быть связаны с использованием параметров -link и -linkoffline. Важным свойством внешнего ссылочного класса является то, что его исходные комментарии обычно недоступны для запуска Javadoc. В этом случае эти комментарии не могут быть унаследованы.

Обратите внимание, что Javadoc для этих классов по-прежнему не будет наследоваться. Тем не менее, теперь вы можете ссылаться на него, вот так:

public class MyMap implements java.util.Map {
    ...
    /**
     * @see java.util.Map#isEmpty()
     */
    @Override
    public boolean isEmpty() {
        ...
    }
}

[РЕДАКТИРОВАТЬ]

@see тег есть для иллюстрации. Javadoc должен автоматически сгенерировать ссылку "Specified By", чтобы вы могли вообще пропустить комментарий Javadoc.

Источник
Другие вопросы по тегам