Исправляем неработающие пути в ASDoc?

StackOverflow https://stackoverflow.com/questions/934176

  •  06-09-2019
  •  | 
  •  

Вопрос

Этот вопрос касается использования ASDoc для создания документации из AS3.Я делаю это не из Flex или чего-то еще, а просто использую командную строку, и хотя все работает нормально и ASDoc не возвращает никаких ошибок, некоторые ссылки в полученной документации не работают.

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

Например, скажем, я документирую myPackage.MyClass.Если MyClass имеет свойство под названием MyProperty, и где-то в своих документах я включаю такую ​​строку:

@see #MyProperty

тогда документы анализируются правильно, и ссылка «См. также:» создается правильно, но в конечном итоге она указывает на 

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

где, конечно, в реальной файловой системе есть только один myPackage папка.

Соответствующая часть моей команды ASDoc выглядит следующим образом:

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"

Возможно, мне не хватает какого-то аргумента ASDoc, который бы определял базовый URL-адрес для ссылок или что-то в этом роде?Если бы это была обычная ошибка, она была бы очевидна для многих, но я не могу найти никаких результатов в Google по этой проблеме, поэтому моя рабочая гипотеза состоит в том, что это не происходит с людьми, запускающими ASDoc из Flex, возможно, из-за некоторых настроек, которые я установил. опустил.

Спасибо за любую помощь!

По предложению TypeOneError я попробовал разные виды ссылок @see.Я обнаружил, что они работают нормально:

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

пока они не работают:

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

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

Я также просмотрел HTML-код и обнаружил, что проблема не в базовом URL-адресе страницы или чем-то еще, а просто в противоречивых ссылках.Итак, в ряду последовательных @see ссылки, некоторые из них ссылаются на ClassName.html и некоторая ссылка на package/ClassName.html, по правилам, указанным выше.Все это, кстати, справедливо независимо от того, просматриваются страницы во фреймах или нет.

Дополнительную информацию, если я что-нибудь придумаю, но идеи обходных путей приветствуются.

Обновлять: Еще несколько подробностей:Я не уверен в своей точной версии SDK, за исключением того, что она сопровождала Flex 3, но если я запускаю ASDoc без аргументов, он сообщает: Adobe ASDoc Version 3.3.0 build 4852.Я запускаю все это в Windows XP из командного файла, помещенного в каталог пути к классам.

Частичное решение: все мои проблемы, кроме одной, были решены путем обновления до бета-версии Flex 4 SDK 4.0.0.7219 (и использования распространяемого в ней ASDoc).Теперь все мои @see теги работают как положено.Единственная остающаяся проблема заключается в том, что всякий раз, когда у меня есть метод, возвращающий класс, являющийся частью моей документации, ASDoc просто искажает ссылку.Например, если у меня есть метод, подпись которого ClassA#getB():ClassB, то там, где это показано в документации, текст «ClassB» ссылается на «packageName:ClassB.html» вместо «packageName/ClassB.html».Казалось бы, это простая ошибка.Блех.

Это было полезно?

Решение

ASDoc бесконечно разочаровывает.Пробовали ли вы явно добавить полное имя пакета/класса в @see, т.е.:

@see myPackage.myClass#MyProperty

Чтобы посмотреть, имеет ли это значение?

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

Я провел несколько тестов на основе ваших результатов, и внутренний маркер свойств у меня работает.то есть

@see #_dispatcher

Ссылается непосредственно на это свойство на странице (без двойной подпапки).Я думаю, возможно, тебе стоит переосмыслить, как ты управляешь командой.Например, моя кодовая база настроена следующим образом:

/src
    /com
        /bkwld
            /fetch

Обычно я запускаю asdoc внутри «src»:

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

Я попробовал все это в Fetch.as, и все они работали как положено:

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

Сначала я попал на страницу FetchItem, второй — на страницу Logger в другом пакете, а третий — на страницу с защищенными методами Fetch.

Просто из любопытства... какую версию SDK вы используете?

Другие советы

Я думаю, проблема в твоей линии

-doc-источники myPackage

Указание '.' Там вместо «mypackage» должно быть исправлено его (так что сделайте его идентичным вашему исходному пути)

Я написал простой скрипт Python, который исправляет пути, неправильно сгенерированные asdoc в упомянутом выше случае.А именно, если есть метод MyMethod (V: MyClass, ...) asdoc неправильно генерирует ссылку href = "../ mypackage: myclass" Сценарий исправят эту замену:по /

Я должен заметить, что документы, которые я создаю, имеют довольно «плоскую» структуру, то есть один пакет с кучей классов.Я понятия не имею, работает ли исправление с более сложными структурами документации.

В любом случае, если кто-то захочет опробовать скрипт, буду рад его прислать.

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top