Унаследовать Javadoc, не создавая документы для унаследованного источника - PullRequest
Новая
       30

Унаследовать Javadoc, не создавая документы для унаследованного источника

6 голосов
/ 07 февраля 2011

Я бы хотел class B наследовать Javadoc от интерфейса, который он реализует, interface A. Я включил источник для interface A в мою команду Javadoc, и class B правильно наследует документацию.

Теперь мне интересно, могу ли я сделать ссылки, которые он генерирует, указывать на документацию interface A в Интернете, а не дублировать ее на моем сайте, то есть ссылки "Указано:" будут ссылаться на внешнюю страницу .

Возможно ли это?

Ответы [ 2 ]

3 голосов
/ 07 февраля 2011

Возможно, да. Чтобы иметь возможность включать унаследованную документацию, источник интерфейса A должен быть найден в исходном пути javadoc, но не должен быть в списке пакетов, переданных в javadoc для создания документации. Для связывания используйте параметр -link. Я только что попробовал это (с задачей Ant Javadoc): 

<javadoc destdir="docs">
  <sourcepath>
    <!-- source of your class B -->
    <pathelement location="src" /> 
    <!-- source of external interface A -->
    <pathelement location="../example-src/src" />
  </sourcepath>

  <!-- your packages, to generate the docs for -->
  <package name="com.personal.myproject.*" />

  <!-- the location of the online documentation -->
  <link href="http://example.com/javadoc/"/>
</javadoc>

Для командной строки javadoc, я думаю, это переводится так (синтаксис Unix, одна строка): 

 javadoc -sourcepath ../example-src/src:src
         -d docs
         -link http://example.com/javadoc/
         -subpackages com.personal.myproject
         (other options...)

, где

  • class B в упаковке com.personal.myproject,
  • interface A в упаковке com.example,
  • мои собственные источники в src,
  • источники для интерфейса A находятся в ../example-src/src.

В примере класса, созданного для этого, javadoc будет копировать документацию из A.methodName() в B.methodName(), но ссылаться на онлайн-документацию в http://example.com/javadoc/com/example/A.html#methodName().

Спасибо, что задали этот вопрос, я всегда хотел сделать это: -)

0 голосов
/ 01 февраля 2017

Огромный кредит Ответ Пауло Эбермана за то, что он указал мне правильное направление для моей установки. Пожалуйста, сначала прочтите этот ответ, так как он имеет смысл, пока я просто предоставляю дополнительный способ настройки решения. <Ч /> Я подумал, что поделюсь тем, с кем я работал, для тех, кто управляет своим проектом с maven и использует maven-javadoc-plugin как часть процесса сборки для создания своих документов.

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

А вот пример, связывающий внешнюю документацию по селену и Java для упаковки в jar-файл для развертывания с моим проектом. Прелесть в том, что эти javadocs в моем проекте просто безосновательно связаны с внешними. 

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <links>
            <link>http://seleniumhq.github.io/selenium/docs/api/java/</link>
            <link>https://docs.oracle.com/javase/${project.java.version}/docs/api/</link>
        </links>
    </configuration>
</plugin>

<ч /> Кстати, если вы нашли что-нибудь полезное на этой странице, пожалуйста, где-нибудь ссылайтесь на него. Найти эту страницу в Google было слишком сложно, и это действительно хорошая вещь.

...