Sfinks: Prawidłowy sposób udokumentowania wyliczenia?

Przeglądając Sfinksa C and C++ domains, wydaje się, że nie ma natywnego wsparcia dla dokumentowania wyliczeń (i znacznie mniej anonimowych wyliczeń). Obecnie używam cpp:type:: dla typu wyliczeniowego, a następnie listy wszystkich możliwych wartości i ich opisu, ale to nie wydaje się być idealnym sposobem radzenia sobie z tym, zwłaszcza, że sprawia, że pewne wartości odnoszą się do bólu (albo Wskazuję tylko typ lub dodam dodatkowy znacznik przed wartością).Sfinks: Prawidłowy sposób udokumentowania wyliczenia?

Czy jest lepszy sposób to zrobić? A w jaki sposób mam obchodzić się z anonimowymi wyliczeniami?

Źródło

2013-07-17 JustSid

Witam Może warto rozważyć użycie doxygen do dokumentacji, ponieważ ma znacznie bardziej natywne wsparcie dla c/C++. jeśli chcesz zachować wyjście sfinksa z dokumentacji, możesz wyprowadzić go z doxygen jako xml, a następnie za pomocą Breathe zajmie to xml i da ci to samo wyjście sfinksa, jakie masz.

Oto przykład udokumentowania enum w formacie doxygen na stronie internetowej poświęconej oddychaniu.

//! Our toolset 
/*! The various tools we can opt to use to crack this particular nut */ 
enum Tool 
{ 
    kHammer = 0,   //!< What? It does the job 
    kNutCrackers,   //!< Boring 
    kNinjaThrowingStars //!< Stealthy 
};

mam nadzieję, że to pomoże.

Źródło

2013-07-24 05:06:47 Zanven

Wolę Sphinx od Doxygen, ponieważ łatwiej jest go dostosować, a sposób, w jaki działa Breathe, nie jest zgodny z tym, w jaki sposób napisana jest nasza dokumentacja (poza tym, patrząc na wynik, wydaje się, że mają podobny problem z prezentowaniem wyliczeń) .Breathe i Doxygen nie są dla nas opłacalnymi opcjami, przepraszam. – JustSid

Projekt na Github, spdylay, wydaje się mieć podejście. Jeden z plików nagłówkowych w https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h ma kodu:

/** 
* @enum 
* Error codes used in the Spdylay library. 
*/ 
typedef enum { 
    /** 
    * Invalid argument passed. 
    */ 
    SPDYLAY_ERR_INVALID_ARGUMENT = -501, 
    /** 
    * Zlib error. 
    */ 
    SPDYLAY_ERR_ZLIB = -502, 
} spdylay_error;

jakiś opis jak to robią w https://github.com/tatsuhiro-t/spdylay/tree/master/doc, który obejmuje zastosowanie generatora API o nazwie mkapiref.py, dostępny na https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py

RST generuje dla tego przykładu jest

.. type:: spdylay_error 

    Error codes used in the Spdylay library. 

    .. macro:: SPDYLAY_ERR_INVALID_ARGUMENT 

     (``-501``) 
     Invalid argument passed. 
    .. macro:: SPDYLAY_ERR_ZLIB 

     (``-502``) 
     Zlib error.

można spojrzeć i zobaczyć, czy to my dla ciebie za dużo.

Źródło

2013-07-28 08:27:54

Dzięki za sugestię Alex - potrzebowałem też tego przykładu! W tej odpowiedzi skorzystałem z możliwości edytowania znaczników Sphinx, które generuje dla przykładu. – Blair

Sfinks: Prawidłowy sposób udokumentowania wyliczenia?

Odpowiedz

Powiązane problemy