Como você cria um link para um _package description_ (não uma classe) no javadoc?

9

(não, isso não é uma duplicata, veja abaixo)

Por que vale a pena, este é o Oracle JDK, 7u72.

Eu não consigo linkar para a descrição do pacote, embora eu precise, já que informações importantes são mencionadas lá, mas não consigo fazer isso a cada vez; quando tento e {@link my.package.name} ou digo para as pessoas irem e @see my.package.name (ou até mesmo um link para uma descrição de pacote de uma biblioteca externa), a ferramenta javadoc relata que não pode encontrar o link ...

Então, como faço esses links?

OK, então, é dito que aqui é a resposta, mas não :

  • a solução proposta funciona apenas para pacotes dentro do seu próprio código; Quero poder vincular-se à descrição do pacote de outras bibliotecas;
  • Eu quero que esses links sejam válidos em package-info.java e javadoc de classe "simples" também.

Então, isso não é uma duplicata.

    
por fge 13.12.2014 в 20:17
fonte

1 resposta

2

Não é tão simples quanto usar a sintaxe da tag {@link package.class#member} , mas você pode vincular a documentação do pacote usando a marcação <a href="..."> HTML direta. A chave é saber o URI correto para colocar no atributo href .

O Javadoc exibe arquivos organizados em uma árvore de diretórios corresponde à sua estrutura de pacotes. Para cada pacote, sua descrição está sempre contida em um arquivo chamado package-summary.html localizado em seu diretório correspondente. O texto de descrição real está localizado em uma âncora específica ou próximo a ela, o que varia de acordo com a versão do Doclet. O nome da âncora pode ser anexado como um identificador de fragmento a qualquer um dos URIs abaixo, se você quiser pular diretamente para o corpo da descrição em vez do topo da página do pacote.

  • No Java 7, a âncora de descrição do pacote foi denominada description , representada como o identificador de fragmento #description .
  • No Java 8, a âncora foi renomeada package.description , representada como o identificador de fragmento #package.description .

Documentação local (navegando em pacotes dentro do seu próprio código):

  • Em qualquer aula, para se referir ao seu pacote próprio :% <a href="package-summary.html">link text</a>

  • Na classe com.example.foo.MyClass para se referir ao pacote com.example pai *:
    <a href="../package-summary.html">link text</a>

  • Na classe com.example.foo.MyClass para se referir ao pacote com.example.bar irmão *:
    <a href="../bar/package-summary.html">link text</a>

  • Na classe com.example.foo.MyClass para se referir ao pacote com.example.foo.fizz.buzz filho *:
    <a href="fizz/buzz/package-summary.html">link text</a>

Todos esses exemplos assumem que os pacotes de destino são, na verdade, pacotes ; em outras palavras, as classes existem nesse nível. Se, em vez disso, com.example fosse um prefixo comum para todos os pacotes, mas não uma única classe declarada package com.example; , o segundo exemplo acima seria um link morto porque nenhum arquivo de resumo teria sido gerado em com / example / package-summary.html .

A maior desvantagem é que é improvável que as ferramentas de refatoração consertem links em seu Javadoc se você reestruturar ou renomear seus pacotes.

* Sim, eu entendo que, logicamente, em Java, os pacotes não possuem relacionamentos "pai" ou "filho" oficiais. No entanto, a estrutura de diretórios usada para organizar os arquivos em pacotes tem tem semântica pai-filho, e é por isso que estou me referindo aqui.

Documentação remota (vinculada de um URL ou caminho de arquivo):

A documentação vinculada funciona essencialmente da mesma maneira que a documentação local, mas com diferentes destinos de HREF de marca de âncora. Por exemplo, a vinculação à documentação pública na Web usará um endereço http:// absoluto. O link para outra biblioteca em algum outro lugar no sistema de arquivos local ou corporativo também pode usar caminhos relativos ou absolutos.

Tenha em mente que, ao usar o recurso de link da ferramenta Javadoc, ele está basicamente fazendo a mesma coisa. Ele lê um arquivo package-list da árvore de diretórios vinculados para saber quais pacotes existem no lado remoto e, em seguida, qualquer documentação referenciada desses pacotes usa o URI apropriado nos links gerados.

Por exemplo, suponha que você esteja vinculando à API Java de:
http://docs.oracle.com/javase/7/docs/api/

Em seguida, para consultar a descrição do pacote java.util.concurrent , anexe a estrutura de diretórios java/util/concurrent/ ao URI de base e adicione package-summary.html no final. (Ou apenas copie-o do seu navegador da Web.) :-)

  

link

Novamente, há uma desvantagem de que, se a documentação da API externa for movida ( ahem , Oracle), quando você atualizar sua configuração de Javadoc para apontar para um novo link, suas tags {@link ...} poderão funcionar, mas qualquer marcação HTML manuscrita para esses arquivos de pacote estará desatualizada.

    
por William Price 17.12.2014 / 10:33
fonte