Как задокументировать свойство, объявленное в другом файле, с помощью Doxygen?

Я использую mogenerator для генерации классов CoreData. Mogenerator выпускает классы машин и людей. Разработчик не должен изменять сгенерированные компьютером классы, так как они генерируются каждый раз, когда вызывается mogenerator. Человеческие классы, однако, могут быть изменены по усмотрению разработчика.

Машинные классы содержат объявление каждого свойства объекта CoreData. В Doxygen, как один документ документирует свойство, определенное в файле A, из файла B?

РЕДАКТИРОВАТЬ: Добавлен пример, чтобы проиллюстрировать вопрос

Пример:

В конечном итоге цель здесь иметь нечто похожее на пример ниже.

FileA.h (не может быть изменено)

@interface FileA : NSObject
{
   NSString* myProperty;
}
@end

FileB.h

#include "FileA.h"

@interface FileB : FileA
{
   /**
    * @property myProperty
    *
    * This is the documentation of "myProperty" 
    * defined in FileA but documented in FileB
    */
}
@end

Пробовал (блок документации внутри @interface FileB @end bock):

@property myProperty - Doxygen не связывает документацию со свойством.

\ property myProperty - Doxygen не привязывает документацию к свойству.

@property FileA:: myProperty - Doxygen не связывает документацию со свойством и генерирует; предупреждение: не найден однозначно совпадающий член класса для FileB:: myProperty

\ property FileA:: myProperty - То же самое

Решение

FileB.h

#include "FileA.h"

   /**
    * @property FileA::myProperty
    *
    * This is the documentation of "myProperty" 
    * defined in FileA but documented in FileB
    *
    * Documentation block MUST BE outside FileB class
    *
    */

@interface FileB : FileA
{
}
@end

2 ответа

Решение

Неясно (для меня) хотите ли вы FileA документироваться, но вы не можете вставить документацию в FileA.hили, если хотите FileA быть недокументированным, но иметь его членов в (документированном) производном классе FileB,

Если это первое, вы можете предоставить документацию для класса FileA в FileB.hэто будет выглядеть примерно так:

/**
 * @class FileA
 * Documentation for FileA
 *
 * @var FileA::myProperty
 * Documentation for myProperty
 */

/**
 * Documentation for FileB
 */
@interface FileB : FileA
{
}

@end

Это приведет к занятиям FileA а также FileB появляться в сгенерированных документах, с myProperty зарегистрирован как член FileA,

Если это последнее, вы могли бы объявить myProperty как член FileB, но используйте защиту препроцессора, чтобы включить объявление только при генерации вашей документации, что-то вроде:

/**
 * document FileB
 */
@interface FileB : FileA
{
#ifdef DOXYGEN
    /**
     * This is the documentation of "myProperty" 
     * defined in FileA but documented in FileB
     */
    NSString* myProperty;
#endif
}

@end

Это приведет к FileB документироваться как myProperty был одним из его членов. Имейте в виду, что если декларация myProperty изменения в FileA, вам придется вручную обновить FileBдекларация, чтобы отразить эти изменения.

Вы можете ссылаться на ахор (например, файлы, пространства имен, классы, функции, переменные, перечисления и т. Д.), Используя Doxygen's ref команда с использованием, например,

\ref variable_name

Если переменная, которую вы хотите задокументировать, не находится в локальном пространстве имен или области, вы можете добавить к имени переменной префикс namespace::, где namespace это область или класс, в котором определяется переменная, на которую вы ссылаетесь. Например, рассмотрим следующие два файла (модифицированные из примеров в руководстве по Doxygen):

Файл 1:

///  A test class.
/**
  A more elaborate class description.
*/
class Test
{
  public:

  /// An enum.
  /** More detailed enum description. */
  enum TEnum {
               TVal1, ///< Enum value TVal1.
               TVal2, ///< Enum value TVal2.
               TVal3  ///< Enum value TVal3.
             }
      /// Enum pointer.
      /** Details. */
      *enumPtr,
      /// Enum variable.
      /** Details. */
      enumVar;

  /// A constructor.
  /**
    A more elaborate description of the constructor.
  */
  Test();
};

Файл 2:

//  Another test class.
/**
  This class depends on the variable \ref Test::TEnum, defined in another file.
  It doesn't, actually, but I've said it does.
*/
class AnotherTest
{
  public:

  /// A constructor
  AnotherTest();

};

Вот TEnum определяется в классе Test в первом файле. Таким образом, во втором файле мы добавляем префикс имени переменной к классу, в котором она определена, т.е. Test::TEnum,

См. Принятый ответ на вопрос. Ссылки на статические переменные const, объявленные в пространстве имен, для получения дополнительной информации о префиксе глобального пространства имен. ::,

Другие вопросы по тегам