Почему Javadoc не заставляет мои подклассы наследовать документацию от классов Java? - PullRequest
7 голосов
/ 23 мая 2011

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

Это Javadoc по умолчанию, который поставляется с обновлением JDK 6 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 <a href="http://download.oracle.com/javase/6/docs/api/" rel="nofollow">http://download.oracle.com/javase/6/docs/api/</a> com.example из каталога javadoc-test. У меня есть каталог bin jdk6 в моем параметре пути.

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

Edit:

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

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

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

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

Ответы [ 2 ]

3 голосов
/ 23 мая 2011

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

1 голос
/ 24 мая 2011

Вы можете сделать ссылку на официальный 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() {
        ...
    }
}

[EDIT]

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

...