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

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

1 голос
/ 11 января 2012

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

Машинные классы содержат объявление каждого свойства сущности Core Data.В 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):

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

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

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

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

Solution

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 ]

1 голос
/ 12 января 2012

Неясно (для меня), хотите ли вы, чтобы документ 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, чтобы отразить эти изменения.

0 голосов
/ 11 января 2012

Вы можете ссылаться на ахор (например, файлы, пространства имен, классы, функции, переменные, перечисления и т. Д.), Используя команду Doxygen * 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, объявленные в пространстве имен , для получения дополнительной информации о префиксе глобального пространства имен ::.

...