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