Fixação caminhos quebrados em ASDoc?

Question

Esta questão preocupações usando ASDoc para criar documentação de AS3. Eu não estou fazendo isso a partir de Flex ou qualquer coisa, apenas usando a linha de comando, e apesar de tudo funciona bem e ASDoc não devolve quaisquer erros, alguns dos links na documentação resultante são quebrado.

Especificamente, em todos os lugares, onde existem ligações para as propriedades ou métodos em outras partes da documentação (incluindo na mesma classe), a ligação enrola-se a duplicação da pasta correspondente ao pacote.

Por exemplo, digamos que eu estou documentando myPackage.MyClass. Se MyClass tem uma propriedade chamada MyProperty, e em algum lugar em meus docs I incluem uma linha como esta:

@see #MyProperty

, em seguida, os documentos são analisados ??corretamente eo "Ver também:" link é criado corretamente, mas ele acaba apontando para

.../output_directory/myPackage/myPackage/MyClass.html#MyProperty

onde é claro, no sistema de arquivo real há apenas uma pasta myPackage.

A parte relevante dos meus ASDoc olhares comando como este:

asdoc
 -source-path .
 -doc-sources myPackage
 -output D:\dev\repository\docs\myPackage_docs
 -external-library-path "C:\Progra~1\Adobe\flex_sdk_3\frameworks\libs\player\10\playerglobal.swc"

Am I talvez faltando algum argumento ASDoc que especifique o URL base para links, ou algo nesse sentido? Se este era um erro simples que seria evidente para muitos, mas não consigo encontrar nenhum resultados do Google para o problema, por isso a minha hipótese de trabalho é que isso não acontece com as pessoas que executam ASDoc de Flex, talvez por causa de algum ajuste I 've omitidos.

Obrigado por qualquer ajuda!

---

Por sugestão de TypeOneError, eu tentei diferentes tipos de ligações @see. Descobri que estes funcionam bem:

• @see some.package
• @see ClassName
• @see ClassName#property

enquanto estes não funcionam:

• @see #property
• @see full.package.ClassName
• @see full.package.ClassName#property

O que é um pouco pior é que, embora todos os links de navegação funcionar, o mesmo caminho dobrou ocorre em links de tipo gerado automaticamente. Por exemplo, onde ele mostra a assinatura de cada método, quando o método retorna uma classe que está na documentação, que ligação é interrompida.

Eu também tive um olhar para o HTML, e descobriu que o problema não parece estar com URL base da página ou qualquer coisa, é apenas ligações inconsistentes. Assim, em uma linha de links @see consecutivos, alguns deles apontam para ClassName.html e alguns link para package/ClassName.html, pelas regras mostradas acima. Tudo isso, por sinal, é verdade independentemente de se as páginas são vistas em quadros ou não.

Mais informações se eu descobrir nada, mas idéias para soluções alternativas são bem vindos.

---

Atualização: Mais alguns detalhes: Eu não tenho certeza da minha versão exata SDK, exceto que ele acompanhou Flex 3, mas se eu executar ASDoc sem argumentos, ele relata: Adobe ASDoc Version 3.3.0 build 4852. Estou correndo tudo isso no Windows XP, a partir de um arquivo de lote colocado no diretório classpath.

---

solução parcial: todos, mas um dos meus problemas foram resolvidos com a atualização para a versão 4.0.0.7219 beta do Flex 4 SDK (e usando o ASDoc nela distribuído). Agora, todas as minhas marcas @see funcionar como esperado. O único problema restante é que, onde quer que eu tenho um método que retorna uma classe que faz parte da minha documentação, ASDoc simplesmente mangles o link. Por exemplo, se eu tenho um método cuja assinatura é ClassA#getB():ClassB, então onde que é mostrado na documentação, o texto "ClassB" links para "packageName: ClassB.html" em vez de "packageName / ClassB.html". Este parece ser um bug simples. Bleh.

Answer 1

ASDoc é frustrante para nenhum fim. Já experimentou explicitamente adicionando o nome completo do pacote / classe para o @see, ou seja:

@see myPackage.myClass#MyProperty

Para ver se isso faz a diferença?

Editar

Eu corri alguns testes com base em suas conclusões e o marcador de propriedade interna está funcionando para mim. i.

@see #_dispatcher

Links diretamente para essa propriedade na página (sem sub-pasta de casal). Eu acho que talvez você precisa repensar como você está executando o comando. Por exemplo, a minha base de código é configurado da seguinte maneira:

/src
    /com
        /bkwld
            /fetch

Eu normalmente executar ASDoc dentro "src":

asdoc -source-path . -doc-classes com/bkwld/fetch/Fetch

Eu tentei tudo isso em Fetch.as e todos eles funcionou como esperado:

*  @see FetchItem
*  @see com.bkwld.utils.Logger
*  @see #_dispatcher

Primeiro me levou para a página FetchItem, segundo me levou para a página Logger em um pacote diferente, e terceiro pulou da página para os métodos protegidos de Fetch.

Só por curiosidade ... qual a versão do SDK você está usando?

Answer 2

Eu acho que o problema é a sua linha

-doc-fontes MyPackage

Especificando '' lá em vez de 'MyPackage' deve consertá-lo (para torná-lo idêntico ao seu caminho de origem)

Answer 3

Eu escrevi um script Python simples que corrige os caminhos incorretamente gerado pelo ASDoc no caso mencionado acima mencionados. Ou seja, se houver um myMethod método (v: MyClass, ...) ASDoc gera incorretamente o link href = "../ mypackage: Minhaclasse" O script irá corrigir isso substituindo o: por um /

Eu deveria notar que os docs que eu estou gerando têm uma estrutura muito "flat", ou seja, um único pacote com um monte de classes. Eu não tenho idéia se a correção funciona com estruturas de documentação mais complexos.

De qualquer forma, se alguém quiser experimentar o roteiro, eu vou ser feliz para enviá-lo.