Сообщения распространенной ошибки

• Q: При выполнении gatherheaderdoc, я добираюсь, сообщение об ошибке “Используя флаг-d требует HTML:: модуль FormatText. Для установки его введите: sudo cpan HTML:: FormatText”.

• A: Генерация набора документа требует двух модулей Perl, не присутствующих в OS X до 10,7. Для установки тех модулей войдите в систему как администраторский пользователь, затем введите:

  sudo cpan HTML::FormatText

  sudo cpan HTML::TreeBuilder

  Введите свой пароль администратора, когда запрошено. Для получения дополнительной информации посмотрите cpan страница справочника и http://www .cpan.org/.

• Q: При выполнении gatherheaderdoc, я получаю ошибку от чего-то названного resolveLinks, говорящим “ошибку I/O: ошибка кодера”. Что продолжается?

• A: У Вас есть заголовочный файл, не записанный в UTF-8. Измените кодирование для того файла путем добавления @encoding или @charset запись в @header тег.

  Начинаясь в HeaderDoc 8.8, HeaderDoc пытается обнаружить это автоматически. Если Вы видите эту ошибку в HeaderDoc 8.8 или позже, зарегистрируйте ошибку и включите копию заголовка.

• Q: HeaderDoc продолжает предупреждать меня, что моя версия LibXML2 слишком стара. Как я решаю эту проблему?

• A: Получите более свежую версию LibXML2 от http://www .xmlsoft.org.

• Q: Я пытаюсь сделать @link к методу, но HeaderDoc настаивает, что не мог быть найден myMethodname%58.

• A: Начиная в HeaderDoc 8.5, необходимо использовать двоеточия на имена методов в тегах @link, вместо того, чтобы заменить их %58.

• Q: HeaderDoc дросселирует на классах со множественным наследованием.

• A: Обновление к HeaderDoc 8.5.

• Q: Почему HeaderDoc не делает предварительной обработки C? Я думал, что Вы сказали, что эта версия сделала.

• A: Это делает, но необходимо указать дополнительный флаг, -p, вызвать это поведение.

• Q: C предварительно обрабатывают, сохраняет включая неправильные файлы.

• A: HeaderDoc не имеет никакого способа знать, что финал установил расположение заголовочных файлов. Для работы правильно это зависит от всех заголовочных файлов, имеющих уникальное имя. Переименуйте свои заголовочные файлы так, чтобы никакие два файла не имели точно то же имя.

• Q: Я продолжаю получать ошибку “Измененное имя (oldname-> newname)”.

• A: Это обычно вызывается одним из следующего:

  • 1. Многократные блоки @discussion. Удалите одного из них.

  • 2. Дополнительный маркер макроса препроцессора после близкой круглой скобки в объявлении функции. HeaderDoc думает, что Вы пишете K&R C объявление. Или используйте @ignore, чтобы проигнорировать маркер или явно повысить в цене макрос препроцессора и включить предварительную обработку C.

• Q: HeaderDoc говорит, “Не может открыться <имя файла> для макросов доступности”.

• A: Ваша установка, вероятно, отсутствует Availability.list файл. В Xcode 4.3 и позже, это живет в /usr/share/headerdoc/. В OS X v10.6 и v10.7 с XCode 4.2.1 и ранее, это жило в /System/Library/Perl/Extras/version/HeaderDoc. В OS X v10.5 и ранее, это жило в /System/Library/Perl/version/HeaderDoc.

• Q: Я получаю ошибку “Конфликтные объявления для функции/метода ($name1) вне класса. Это, вероятно, не, что Вы хотите”.

• A: Как это говорит, у Вас есть две функции, которые не являются элементами класса, но имеют то же имя (или Вы забыли помещать разметку HeaderDoc на класс включения). Это законно в C++, но обескуражено, потому что apple_ref синтаксис не предоставляет гарантию уникальности в этих экземплярах. HeaderDoc пытается уклониться от этого путем проставления подписи, когда он видит эту ситуацию, но как правило, Вы не должны полагаться на это поведение, если Вы заботитесь о apple_ref разметке.

• Q: HeaderDoc извергает предупреждения о “Проанализированном параметре <вздор>, не найденный в объявлении функции/метода/определения типа <вздор>”.

• A: Возможности, Вы сделали типографскую ошибку при добавлении @param или @field маркеры в комментарии HeaderDoc. Проверьте свое написание тщательно и помните ту капитализацию вопросы.

• Q: HeaderDoc продолжает говорить “Теговый параметр <вздор>, не найденный в объявлении функции/метода/определения типа <вздор>”.

• A: Вы включили строгий параметр/поле, сверяющийся -t флаг. Выключите его, если Вы не хотите те предупреждения.

• Q: HeaderDoc говорит, что “Не соответствуют фигурные скобки/круглые скобки/квадратные скобки Фигурных скобок/класса. У нас может быть проблема”.

• A: Это обычно означает точно, что это говорит. Если Вы в зависимости от макроса препроцессора C, чтобы заставить фигурные скобки соответствовать, необходимо попытаться избежать делать так. Если Вы не можете избежать этого, удостоверьтесь, что Вы включаете предварительную обработку C и добавляете разметку HeaderDoc к макроопределению.

• Q: HeaderDoc говорит “Конец дерева синтаксического анализа, достигнутого при поиске соответствия определения”.

• A: Это обычно вызывается или размещением HeaderDoc сразу, комментируют до близкой изогнутой фигурной скобки или путем размещения неправильного тега типа HeaderDoc в комментарий (такой как предшествование a typedef с @function комментарий).

• Q: HeaderDoc не говорит “Найденного объявления соответствия. Фамилия была <вздор>”.

• A: Это обычно вызывается или размещением HeaderDoc сразу, комментируют до близкой изогнутой фигурной скобки или путем размещения неправильного тега типа HeaderDoc в комментарий (такой как предшествование a typedef с @function комментарий).

• Q: Я получаю ошибку, “Неспособную обработать #define макрос “<имя>”.

• A: Зарегистрируйте ошибку.

• Q: HeaderDoc говорит “WARNING: многократные соответствия, найденные для символа “<вздор>”. Только первый символ соответствия будет соединен”.

• A: У Вас есть многократные символы с тем же именем (возможно в различных файлах, или возможно различных типах — например, функция и a #define). HeaderDoc не имеет никакого способа знать, какой из тех двух или больше «myname» символов Вы говорите о том, когда Вы говорите @link myname. Для решения этой проблемы посмотрите в HeaderDoc-сгенерированном HTML для желаемого места назначения. Найдите привязку к имени, которая похожа <a name=”//apple_ref/...”> и вместо того, чтобы просто дать имя, дайте все содержание той привязки.

• Q: HeaderDoc говорит ‘WARNING: никакой символ, соответствующий “<вздор>”, не найден. Если этот символ не находится в этом файле или классе, необходимо указать его с API касательно тега (например, apple_ref)’.

• A: Вы не можете обрабатывать все необходимые файлы сразу, или HeaderDoc может чувствовать себя расшатанным. В любом случае, для решения этой проблемы посмотрите в HeaderDoc-сгенерированном HTML для желаемого места назначения. Найдите привязку к имени, которая похожа <a name=”//apple_ref/...”> и вместо того, чтобы просто дать имя, дайте все содержание той привязки.

• Q: HeaderDoc выпускает предупреждение “WARNING: resolveLinks, не установленный. Проверьте свою установку”.

• A: Убедитесь, что Вы устанавливаете правильно. Во-первых, введите “make”, тогда “make realinstall”.

• Q: HeaderDoc говорит “WARNING: Неожиданная headerdoc разметка нашла во <вздоре> объявление”.

• A: Возможности, Вы следовали одному комментарию HeaderDoc с другим комментарием HeaderDoc без чего-либо промежуточного.

• Q: HeaderDoc предупреждает “Незавершенный тег @link (стартовое поле было: @link...)”.

• A: Если Вы используете JavaDoc-стиль @link тегирующий ({@link symbol Link Text}), не забывайте близкую изогнутую фигурную скобку. Если Вы делаете HeaderDoc-стиль @link тегирующий (@link symbol Link Text @/link), не забывайте @/link.

• Q: HeaderDoc сказал “Ошибку синтаксического анализатора: пустой внешний тип”.

• A: Это - вероятно, ошибка, если Вы не делаете что-то действительно странное с директивами препроцессору, нарушающими нормальные синтаксические правила C (когда Вы должны или @ignore посторонние маркеры или включать C, предварительно обрабатывающий). В целом, тем не менее, необходимо, вероятно, зарегистрировать ошибку.

• Q: HeaderDoc продолжает говорить “метод Objective C, найденный вне класса или интерфейса (или в классе, или взаимодействуйте через интерфейс, который испытывает недостаток в разметке HeaderDoc)”.

• A: Удостоверьтесь, что Вы должным образом тегировали объявление класса включения или объявление интерфейса.

• Q: HeaderDoc продолжает говорить “Неспособный найти дерево синтаксического анализа. Зарегистрируйте ошибку”.

• A: Это не должно происходить; зарегистрируйте ошибку.

• Q: HeaderDoc продолжает говорить, “Не удалось найти состояние синтаксического анализатора. Используя медленный метод”.

• A: Если у Вас есть класс, запускающийся с маркера препроцессора (такой как DeclareStructors(MyClass) или подобный), это повредит вещи плохо. Существует два решения. Самое простое решение состоит в том, чтобы добавить @ignorefuncmacro DeclareStructors (или независимо от того, что макро-имя, оказывается,) в Вашем @header объявление.

• Альтернативная фиксация должна удостовериться, что Вы обрабатываете заголовочный файл, содержащий макрос в то же время, что и Вы обрабатываете класс. Включите C, предварительно обрабатывающий с -p флаг. Наконец, добавьте комментарий HeaderDoc перед макроопределением.

• Если эта проблема не вызывается при помощи макроса, зарегистрируйте ошибку. Этот случай нейтрализации не должен влиять на вывод, как бы то ни было.

• Q: HeaderDoc продолжает говорить, ‘Не мог определить, включают имя файла для “#include FW (Углерод, CarbonEvents.h)”’ или подобный.

• A: Идеально, необходимо использовать стандарт, включают синтаксис файла. Если это не возможно, необходимо включить препроцессор C с -p отметьте, включайте файл, содержащий макрос FW на командной строке, и добавьте разметку HeaderDoc к тому макросу.

• Q: HeaderDoc говорит “Неизвестный regexp разделитель «...». Зарегистрируйте ошибку.

• A: Это не должно происходить; зарегистрируйте ошибку.

• Q: HeaderDoc продолжает говорить “Неизвестное ключевое слово <вздор> в проанализированном блоком объявлении”.

• A: Удостоверьтесь, что заголовок компилирует правильно с gcc. Если это делает, зарегистрируйте ошибку.

Другие сообщения об ошибках обычно попадают в одну из двух категорий: очевидные ошибки (такие как “Неизвестный тег @whatever в функциональном комментарии”) или совершенно непонятный (такие как “Ошибка синтаксического анализатора: пустой внешний тип”). В случае прежнего фиксируйте надлежащее объявление. В случае последнего просьбы регистрируют ошибку. Который приносит нам к последнему вопросу....

• Q: Как я регистрирую ошибку?

• A: Прежде, чем зарегистрировать ошибку, необходимо подписаться на список рассылки Хеадердок-дева на lists.apple.com. Спросите, видел ли кто-либо еще проблему. В противном случае необходимо зарегистрировать ошибку. Для подписки посетите http://lists .apple.com/mailman/listinfo/headerdoc-dev.

• Если Вы - участник ADC с доступом к bugreport.apple.com, зарегистрируйте ошибку через тот механизм. Корректный компонент является «HeaderDoc» с версией «Дарвин».

Неожиданное поведение

• Q: Часть моего Ruby, JavaScript или сценариев Tcl пропускает содержание.

• A: HeaderDoc 8.8 не анализировал регулярные выражения ни на каком языке кроме Perl.

  На большинстве языков это не имеет никакого значения, потому что регулярные выражения сохранены в строках и соблюдают нормальные строковые правила парсинга. В Python это не имеет никакого значения, потому что его синтаксический анализатор базируется исключительно на глубине добавления отступа. Это оставляет три языка, на которых регулярные выражения могут вызвать проблемы: Ruby, JavaScript и Tcl.

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

  Рекомендуемое решение должно обновить до HeaderDoc 8.9, который должен решить проблему. Если обновление не возможно, можно работать вокруг этой проблемы путем добавления холостого регулярного выражения в предыдущей или последующей строке, содержащей необходимое открытое соответствие, или близко заключите в фигурные скобки, круглая скобка или кавычка для работы вокруг проблемы. (Это дополнительное регулярное выражение не должно быть в комментарии.)

• Q: Я вижу многократные копии своих функций/определений типов/определять /*. Почему?

• A: Вы, вероятно, указали имя в @function тег (или @typedef или...), который отличался от подлинного имени. Удалите неправильное имя или передайте флаг-N HeaderDoc, говорящему, что это для глобального игнорирования любых имен указало в разметке HeaderDoc (HeaderDoc 8.8 и позже).

• Q: Я все еще вижу многократные копии определения типа, но с различными именами.

• A: HeaderDoc, по умолчанию, также генерирует запись для «имен тега» и для каждого имени типа. Можно удалить имена тега путем указания-O (только внешние имена) флаг. В следующем примере имя тега mystruct, и имя типа (a.k.a. “внешнее имя”) mystruct_t:

        typedef struct mystruct {int a;} mystruct_t;

• Q: Почему делает мою функцию/метод/тип/переменную/класс /* имеют имя, которое, кажется, включает весь абзац обсуждения?

• A: Одна из двух вещей является неправильной. Любой Вы включали многократные слова после @function/@typedef/@whatever и также включенный @discussion тег или Вы начали многострочное объявление в конце @function/@typedef/@whatever строка. Не делайте этого. Посмотрите Имена Многословные для получения дополнительной информации.

• Q: Набор моего functions/typedefs/* соединяются с, “См. Также” атрибуты.что происходит?

• A: Вы, вероятно, отметили a typedef с @function комментарий (или некоторое другое неправильное соединение). HeaderDoc предположит, что Вы знали то, что Вы делали и продолжите просматривать код, пока это не находит то, что требовали (функция в этом случае). Все промежуточное будет соединено. Цель для этого состоит в том, чтобы прежде всего позволить Вам отмечать @typedef для a struct сопровождаемый a typedef, но это полезно в других ситуациях также. Фиксируйте неправильно соответствующий комментарий, и проблема должна уйти.

• Q: Когда я добавляю, почему я, не получая ссылки @link теги?

• A: Существует несколько возможных причин:

  • 1. Если Вы использовали apple_ref разметка, Вы, возможно, сделали опечатку.

  • 2. Если бы Вы использовали имя символа, не существовавшее, то Вы получили бы предупреждение при выполнении headerdoc2html и никакая ссылка не будет сгенерирована.

  • 3. @link тегируйте только вставляет запрос на канал в HTML. Для превращения этого в фактическую ссылку необходимо работать gatherheaderdoc (который поочередно работает resolveLinks создать ссылки). Пока Вы не выполните gatherHeaderDoc, все, что Вы будете видеть в HTML, набор особенно отформатированных комментариев.

• Q: Каждый раз я работаю gatherheaderdoc, все пробелы в моих объявлениях уходят. Что продолжается?

• A: Это - ошибка в libxml2 это фиксируется в более свежих версиях. Посетите http://www .xmlsoft.org, чтобы получить более свежую версию (или обновить до OS X v10.4 или позже).

Другие проблемы

• Q: Я смущен. Где я могу получить справку?

• A: Лучшее место для получения справки является списком рассылки Хеадердок-дева. Для подписки перейдите в http://lists .apple.com/mailman/listinfo/headerdoc-dev.