Скрыть специализации шаблона Параметры в Doxygen Output

Question

Я пишу библиотеку, которая широко использует мета-программирования, и имеет классы свойств, таких как

/// Doxygen comments... 
template<class T> 
struct unit_traits<T, typename void_t< 
    typename T::base_unit_type, 
    typename T::conversion_ratio, 
    typename T::pi_exponent_ratio, 
    typename T::translation_ratio>::type> 
{ 
    typedef typename T::base_unit_type base_unit_type;   ///< typedef documentation 
    typedef typename T::conversion_ratio conversion_ratio;  ///< typedef documentation 
    typedef typename T::pi_exponent_ratio pi_exponent_ratio; ///< typedef documentation 
    typedef typename T::translation_ratio translation_ratio; ///< typedef documentation 
}; 

Однако специализация просто деталь реализации (есть в других местах, где специализации используются для завершения рекурсий и т. д.), и он загромождает вывод doxygen, поскольку пользователю библиотеки действительно нужно знать, что доступно unit_traits<someType>::.... Есть ли способ скрыть параметры специализации в документации, желательно без создания фиктивных целей документации?

UPDATE

Просто чтобы быть ясно, я попытался следующие, и они не скрывают специализации:

template<class T> 
    struct unit_traits 
/** @cond */ 
     <T, typename void_t< 
     typename T::base_unit_type, 
     typename T::conversion_ratio, 
     typename T::pi_exponent_ratio, 
     typename T::translation_ratio>::type> 
/** @endcond */ 
    { 
     typedef typename T::base_unit_type base_unit_type; 
     typedef typename T::conversion_ratio conversion_ratio; 
     typedef typename T::pi_exponent_ratio pi_exponent_ratio; 
     typedef typename T::translation_ratio translation_ratio; 
    }; 

и

template<class T> 
     struct unit_traits 
    #ifndef DOXYGEN_SHOULD_SKIP_THIS 
      <T, typename void_t< 
      typename T::base_unit_type, 
      typename T::conversion_ratio, 
      typename T::pi_exponent_ratio, 
      typename T::translation_ratio>::type> 
    #endif 
     { 
      typedef typename T::base_unit_type base_unit_type;    
      typedef typename T::conversion_ratio conversion_ratio;          
      typedef typename T::pi_exponent_ratio pi_exponent_ratio;         
      typedef typename T::translation_ratio translation_ratio;          
     }; 

Answer 1

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

Так, вероятно, вы могли бы сделать что-то вроде этого:

/** Doxgen doc for general-form unit_traits. */ 
template<typename General> 
class unit_traits; 

Теперь вы можете обмануть Doxygen (опять же, предостережение в конце), как это:

#ifndef DOXYGEN_SHOULD_SKIP_THIS 
// Code actually being built. 
template<> 
class unit_traits<int> 
#else // DOXYGEN_SHOULD_SKIP_THIS 
/** Doxygen comment for the int case. */ 
class unit_traits 
#endif // DOXYGEN_SHOULD_SKIP_THIS 
{ 
.... 
}; 

Ваш компилятор будет хорошо с этим. Что касается Doxgen, это либо сработает, либо нет - поскольку на самом деле не действительно C++-код имеет unit_traits оба шаблона, а не, Doxygen либо его купит, либо нет, и даже если это произойдет, следующая версия может не работать.

Очевидно, что вы могли бы сделать что-то подобное, хотя:

#ifndef DOXYGEN_SHOULD_SKIP_THIS 
// Code actually being built. 
template<> 
class unit_traits<int> 
#else // DOXYGEN_SHOULD_SKIP_THIS 
/** Doxygen comment for the int case. */ 
class int_unit_traits 
#endif // DOXYGEN_SHOULD_SKIP_THIS 
{ 
... 
}; 

Поскольку оба пути препроцессора являются действительными C++ (ну, вроде), компилятор и Doxgen должны быть счастливы.

---

Caveat

Лично я считаю, что тот факт, что вы пытаетесь «обмануть» Doxygen показывает, что существует концептуальная проблема. Сильно-шаблонный C++ является пограничным недокументированным, и Doxygen работает лучше, чем я мог бы сделать за миллион лет, но это все еще проблематично.

В подобных случаях я обычно размещаю всю документацию для общего случая и специализации - в комментарии Doxygen для общего случая. Я делаю Doxygen игнорировать специализации (используя препроцессор) и просто помещаю комментарий, отличный от doxygen, по каждому из них, говорящий, что документация в общем случае. По общему признанию, это тоже дерьмо :-)