2002 2003 2004 2005 2006 2007 2008 2009 2010 <2011> 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 | Index | 2002 2003 2004 2005 2006 2007 2008 2009 2010 <2011> 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 |
<== Date ==> | <== Thread ==> |
---|
Subject: | Re: class library header file naming and install conventions |
From: | Ralph Lange <[email protected]> |
To: | [email protected] |
Date: | Tue, 15 Mar 2011 17:49:39 +0100 |
On 15.03.2011 17:20 Jeff Hill wrote:
I would encourage considering the use of a standard tool like doxygen, I think once you start writing in-line documentation it should make future maintenance easier, although I've rarely used it myself because introducing it after-the-fact is hard.Such tools have been around for a long time. People were using them on the VAX when I started here in 1986. I'm sure they have learned a thing or two since then so perhaps I should look closer at doxygen. The argument for use of doxygen type programs is that programmers are more likely to work on their programming language source files, and so if we store the doc there also then maybe they will keep it current. There can also be a standard, consistent, format. The downside maybe is that every manual reads like a reference manual, and we are less likely to have a tutorial. We are maybe more likely to create human friendly documentation with concept structured indexes and html tables if the html is structured by a human?
We won't (ever) win a Pulitzer with our documentation, either way.Doxygen (which looks and works a lot like Javadoc) creates very nice reference documentation from comments in the source files, which is especially nice for library APIs that you want other people to use.
There are IDEs that help you create doxygen for C/C++ very similar to helping you create Javadoc.The internal link references in the html code are created automatically by doxygen. These are always relative, so that you can move around the created doc.
But again: Doxygen is for creating code documentation. Tutorials, user guides, and fiction should use other tools. ~Ralph