Alternativ till doxygen?

[sirGustav]

Jag har använt doxygen ett bra tag, och den gör vad den skall göra, men det blir ganska mycket "kryptiska" kommenterings-spam i mina vackra headers, så jag har nu äntligen tagit mig tid till att titta in på NaturalDocs som förutom snyggare headers arbetar inkrementellt, dvs den dödar inte byggtiden om man vill integrera, och genererar snyggare dokument som default, men dess support för C++ är inte i topp.

Så eftersom jag inte vill sätta alla mina andra roliga projekt på paus i 2 år, finns det några andra vettiga alternativ?

[dooz]

Hmm, med risk för att inte svara särskilt konkret, och gå fort OT, men hur mycket är det du kommenterar för att du ska tycka att det förstör dina headers?

Jag läste rätt nyligen ett påstående som faktiskt ändrade lite hur jag såg på det att kommentera, och det var helt enkelt att en kommentar är ett misslyckande med att göra koden tillräckligt tydlig. Det var i Robert Martins bok "Clean Code", där han säger en hel del vettigt, mycket sånt som egentligen är uppenbart, men det är skönt att höra en kändis säga det också; som det här med att slaviskt kommentera varje parameter i ett funktionsanrop, trots att variabelnamnet heter i princip exakt samma sak som det står i kommentaren.

Flum over, men jag har bara kört Doxygen. Hemma (där jag faktiskt kan påverka utseendet av hela kodbasen, och ändra mig beroende på månens faser) har jag dock bara kört lite halvslaffsigt, och nöjer mig oftast med att använda "///" och "/** bla bla */", och inbillar mig att det kommer att bli bra docs..

[sirGustav]

Det jag menar är att java-doc kommentarer lägger till ~3 rader extra per funktion, och natural-doc lägger till lite fler (~6), men de är inte lika kryptiska. Det är inte riktigt det att jag behöver dokumentation, men att det är trevligt att ha en mapp med en lista över funktioner som finns i mitt util-bibliotek, som man kan referera till. Visst ser man skillnaden och ser vad funktionerna gör, men det är trevligt, och jag dokumenterar inte alla argument, bara de som är vettiga.

Vad dessa gör och skillnaden mellan dem är uppenbar, så de får mer eller mindre bara länkar till varandra

Radnummer Av/På | Expandera/Minimera | Markera allt

1. const vec2 GetNormalized(const vec2& vec)
2. void Normalize(vec2* vec)

medan vad

Radnummer Av/På | Expandera/Minimera | Markera allt

1. const real Remap(const real ol, const real ou, const real v, const real nl, const real nu)

gör, och vad de olika argumenten(som borde ha lite bättre namn) är, är nog inte det

Dessutom hittar jag funktioner som gör samma sak(samt med dåliga namn) när jag tvingas gå igenom koden och se vad den gör

[dooz]

Hmm, testade NaturalDocs i 5 minuter, och det verkade trevligt, tills jag upptäckte att i språk som den inte hade fullt stöd för (C++), så var man tvungen att explicit skriva en topic-rad för att den skulle dokumentera, och jag är redan tillräckligt arg över att behöva skilja på definition och deklaration

Alltså, i ditt remap fall, ställ dig frågan "vad är det jag måste ändra för att slippa skriva en kommentar". Jag misstänkte först att ol, ou betydde "old" och att nl, nu betdde "new" nånting, men eftersom bägge är const, så håller inte den tesen. Då undrar jag om remap (även om den skulle heta remap_nånting_annat_käkt) är rätt term, eftersom jag tolkar en remap (eller i alla fall en map) som en transformation (heh, mappning) från X till Y.

[tetsu]

Själv använder jag i princip bara kommentarer för att dokumentera publika API. Alltså API som andra skall använda, vilket inte har skett på ett par år, så det var ett tag sedan jag använde något sådant verktyg. Senaste var nog NDoc som är för C#.

Angående doxygen, så om fallet är att du tycker det är jobbigt för att kommentererna ligger i klassen så kan man lägga det utanför om man vill.

-- dinheader.h --

Radnummer Av/På | Expandera/Minimera | Markera allt

1.  
2. class Elefant
3. {
4. private:
5.    ...
6. public:
7.    ...
8.    void hoppa( int höjd );
9. };
10.  
11. /** @fn void Elefant::hoppa( int höjd )
12.     Får elfanten att hoppa.
13.     @param höjd Hur högt elefanten skall hopp.
14. */
15.  

Visst, det blir massa "skräp" i headerfilen, men de ligger i alla fall separerat från koden.

[sirGustav]

Det är ett publikt api, som "andra" skall använda. Andra i detta fallet kan vara andra(med tanke på att det är opensource), men lite mer troligt är det bara jag i ett senare skede, då jag inte kan koden

Jag har nu gått igenom wikipedias lista över gratis dokumentations-genererare med full support för C++.
Vad jag kan se så förutom de som har nämnts tidigare så står följande ut: kdoc(google hittar 1.0, den senaste verkar vara 3.0) och robodoc.
kdoc har en javadoc liknande syntax och ser ut att kunna generera snygga dokument men är inte testat på windows.
robodoc har en ganska ful syntax och en enkel html-sida, men har varit med ett tag

Så... efter att ha gått igenom 8+ generatorer så är doxygen och naturaldocs ledande. Natural docs för sitt inkrementella bygg-system och html-sida, doxygen för sin konfigurations-fil, mscgen support och fullt C++ stöd.

Jag misstänkte först att ol, ou betydde "old" och att nl, nu betdde "new" nånting, men eftersom bägge är const, så håller inte den tesen.

Jodå, den håller. Det är bara förkortningar alltihop. o=old och n=new, ungefär som du gissade. v=value, l=lower och u=upper, och funktionen "remappar" från ett "range"(old) till ett annat(new). Så om din karaktärs hälsa går från 0-10 och för närvarande är 5 och du skall rita ut en linje mellan 11-31 baserad på hur mycket hälsa din karaktär har så ger dig Remap(0,10,5,11,31) svaret
Ultimat så skulle range vara en egen struct/pod, men då den bara används som in-parameter och de garanterat sparas undan som antingen konstanter eller som fristående variabler eller kombinationer av de två så ansåg jag att för närvarande kan de vara "fristående".
Men, som jag skrev så hade det blivit mycket tydligare om jag hade döpt de till något vettigare...

Hmm, testade NaturalDocs i 5 minuter, och det verkade trevligt, tills jag upptäckte att i språk som den inte hade fullt stöd för (C++), så var man tvungen att explicit skriva en topic-rad för att den skulle dokumentera, och jag är redan tillräckligt arg över att behöva skilja på definition och deklaration

Det stör mig inte så mycket, deal-breakern för mig verkar nu vara att den inte kan skilja på const och non-const funktioner och båda refererar till samma (non-const) funktion. Jag har även läst att den skall ha problem med operator<.

Angående doxygen, så om fallet är att du tycker det är jobbigt för att kommentererna ligger i klassen så kan man lägga det utanför om man vill.
Visst, det blir massa "skräp" i headerfilen, men de ligger i alla fall separerat från koden.

hmmm, det ser faktiskt inte så dumt ut... tack! Jag gjorde ett litet test nu och vad jag kan se så lyckas den till och med om jag lägger kommentarerna i en separat doc-fil i en undermap, najs, perfekt för mer komplicerad dokumentation . Då är det bara att se om jag kan fixa till html-utdatan så att den ser mer ut som natural-docs.

edit: ok, det ser ut som om doxygens html-konfiguration inte är så pass konfigurerbar så att jag kan få ut natural-docs liknande html-filer, undrar hur lång tid det tar att skriva ett program som parsar xml-filerna för att de skall bli "snyggare"
Det får nog bli ett senare projekt, eftersom jag vill fortsätta på mitt bibliotek. Hur som helst, ser det ut som om natural-docs får ge vika för doxygen kommentarer i en underkatalog.

[sirGustav]

edit: ok, det ser ut som om doxygens html-konfiguration inte är så pass konfigurerbar så att jag kan få ut natural-docs liknande html-filer, undrar hur lång tid det tar att skriva ett program som parsar xml-filerna för att de skall bli "snyggare"
Det får nog bli ett senare projekt, eftersom jag vill fortsätta på mitt bibliotek. Hur som helst, ser det ut som om natural-docs får ge vika för doxygen kommentarer i en underkatalog.

Svaret är att det tog ungefär en heldags arbete för att få fram något som kan klassas snyggt, troligtvis inte ser fullt lika bra ut i andra browsrar än firefox och (endast) visar funktioner med tillhörande dokumentation. Jag har ingen aning hur jag vill visa struct/class i min design så det får jag fundera på, eller så skiter jag i det och kör på den officiella versionen. Jag har lärt mig en hel del web-design när jag suttit med detta och faktiskt äntligen integrerat en syntax-highlighter i web-sammanhang

Doxygen's xml är dock i vissa avseenden riktigt bra och i andra, inte lika fullt funktionellt, men när är allt kommer till kritan är html, css & java-script ganska bökigt, tråkigt och inte fullt så kul som de äkta programmeringsspråken C#/C++