Документировать унаследованные методы Obj-C без предупреждений Doxygen/компилятора?

Предыстория:

Я создаю иерархию составных структур данных словаря в Objective-C и наследую от NSMutableDictionary, чтобы эти классы можно было использовать везде, где требуется NSDictionary/NSMutableDictionary. (Чтобы люди не думали, что я изобретаю велосипед, каждый использует CFMutableDictionaryRef, а также некоторая дополнительная структура, в которой хранятся ключи в отсортированном порядке, порядке вставки и т. д.) В соответствии с документацией Apple я переопределил необходимые Примитивы NSDictionary и Примитивы NSMutableDictionary который используют все остальные методы в этих классах.

Цель:

Поскольку я стремлюсь максимально полно документировать API для своего фреймворка, мне бы хотелось, чтобы документация для моих пользовательских подклассов (создана Doxygen), чтобы включить описания наиболее распространенных методов NS(Mutable)Dictionary, чтобы пользователям не приходилось просматривать другую страницу только для методов, которые наследует конкретный пользовательский словарь без изменений. Кроме того, иногда документация должна отражать другую функциональность, вызванную переопределенными примитивными методами, хотя реализация метода не отличается от NS(Mutable)Dictionary.

Проблема:

Я не получаю ошибок/предупреждений, когда задокументированы только переопределенные методы. Если я добавлю комментарии, которые документируют унаследованные методы, Doxygen жалуется (и не будет создавать указанную документацию), если я не добавлю прототип метода в заголовочный файл. Если я добавлю прототип, компилятор выдаст предупреждение о том, что реализация завершена, поскольку он не включает определение метода для объявленного метода. Очевидно, что это тот случай, когда метод существует в родительском классе, но компилятор настаивает на его реализации, поскольку прототип по существу переопределен в подклассе.

Вопросы:

  • Можно ли заставить Xcode/gcc подавлять предупреждения «определение метода для «X» не найдено» для методов, унаследованных от родительского класса?
  • Можно ли заставить Doxygen создать документацию для метода, для которого не существует описания? Я попытался использовать команду \fn, но получил те же результаты.
  • Можно ли обмануть Doxygen, заставив его думать, что документация, которую я пишу, на самом деле относится к NSMutableDictionary, но при этом она отображается для всех моих пользовательских подклассов?

Изменить:

Насколько я могу судить, ответ на первый вопрос и да, и нет. Технически, используя параметр -Wno-protocol (или снятие флажка с предупреждения «Неполные протоколы Objective-C» в настройках сборки Xcode) действительно приводит к тому, что GCC подавляет предупреждения времени компиляции о классах, которые, по-видимому, не реализуют все методы протокола. Однако это маскирует проблему для классов, которые действительно не реализуют все необходимые методы. Для создания фреймворка, который использует протоколы, это действительно не вариант. В настоящее время GCC, похоже, не знает о методах, унаследованных от связанного (не исходного) родительского класса.


xcode gcc objective-c cocoa doxygen
person Quinn Taylor    schedule 16.06.2009    source источник

Ответы (1)


arrow_upward
2
arrow_downward

Насколько я знаю, ответ на ваши три вопроса: нет.

Я хотел бы обратить ваше внимание на то, что документация Apple не документирует унаследованные методы в документации подкласса.

Более того, NSDictionary и NSMutableDictionary не так уж редки, чтобы нуждаться в напоминании об их наиболее распространенных методах. Для меня достаточно ссылки на существующую документацию, как у вас уже есть.

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

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

- (NSArray *) allValues
{
    return [super allValues];
}
person mouviciel    schedule 18.06.2009
comment
Не нужно привлекать мое внимание к тому, как это делается в документах Apple, я прекрасно об этом знаю. Однако их документация создается с помощью HeaderDoc и ручной настройки. Кроме того, классы не имеют ссылок на свои подклассы, поэтому навигация не так проста, как в Doxygen или Javadoc. Тем не менее, вы прекрасно заметили, что ожидаете, что пользователи будут знать, где найти документы для любых других методов. Соответственно убрал из шапки лишнюю документацию по методам и предупреждения исчезли. Документация включается только тогда, когда метод переопределяется и изменяет унаследованное поведение. Спасибо за Ваш ответ! - person Quinn Taylor; 19.06.2009