Verktyg för att skriva api-dokumentation

Hej sweclockersare!

Jag tänkte höra om ni har något tips om verktyg eller hjälpmedel för att skriva api-dokumentation. Det är så att jag behöver skriva dokumentation för ett api och skulle vilja ha något hjälpmedel för att göra det lite lättare att underhålla och som hjälper till att få det snyggt och prydligt.

Med api-dokumentation som menar jag dokumentation mot ett api som egentligen inte är direkt kopplat till något språk. Det går med andra ord inte använda några verktyg som analyserar kod såsom javadoc, phpdoc eller doxygen.

Tänk scenariot att du exponerar vissa tjänster via ett proprietärt api över http och du skulle vilja dels beskriva filosofin bakom det hela men också beskriva strukturer och format.

Någon som har något tips?

//C

Hej.

Tack för svaret. Jag håller med om det du skriver. Har utvecklat ganska länge så jag känner till problematiken med det hela.

Tycker kommentaren om märkspråk (otroligt fult svenskt ord men vi kör på det) är sund. Har använt Textile och reStructuredText i olika sammanhang förut. Det som gör att jag dock helst skulle vilja ha ett alternativ i detta fall är att det kommer beskrivas en del datastrukturer och klasser med funktioner och att jag gärna skulle vilja ha lite hjälp att presentera dem på ett strukturerat och "snyggt" sätt.

Så jag söker mer ett märkspråk som kan hjälpa mig med programmeringsmässiga detaljer i tillägg förutom den mer generella formateringen.

//C