I've never used Doxygen in the way you mention where we have separate
documentation files but that sounds like a recipe for code going out of
date with the documentation. The comments should definitely be in-line with
the code.
As Daniel mentions, we aren't providing an API to others so we don't have
the same need for publishable documentation that e.g. Qt does.
I'd prefer to stick with status quo -- no documentation formatting of any
kind. It makes it more readable for those of us not using IDEs and doesn't
require that you learn a syntax to document something.
Surely there's some documentation generator out there smart enough to do
something sane with this:
// A class for counting frobs.
//
// Example:
// FrobCounter counter;
// counter.frob();
class FrobCounter {
public:
FrobCounter() : m_frobs(0) {}
~FrobCounter() {}
// Record a frob.
void frob() { m_frobs++; }
private:
// Number of times the FrobCounter has been frobbed.
int m_frobs;
};
On Sat, Jan 3, 2015 at 2:44 PM, Daniel Schürmann <dasch...@mixxx.org> wrote:
> Hi Ferran,
>
> we have discussed the doxygen topic some time ago.
>
>
> https://www.mail-archive.com/mixxx-devel@lists.sourceforge.net/msg03894.html
> There was also a Doxygen docu online, provided from a contributor.
>
> Time has passed and probably the view on this has changed in the team.
> So we may discuss it again.
>
> For today, I am in doubt about the value of the doxygen output itself.
> A IDE with a powerful indexer (I use Eclipse) helps probably much more to
> understand the code
> than a doxygen html output. The power of doxygen is needed for projects
> that are providing an API without necessarily installing the source code,
> but that is not the Mixxx nature.
>
> Even tough I like the idea to add doxygen support to the Mixxx build
> system for a different reason: It encourages the developers to add more
> comments to the source and it unifies the comment style, since the doxygen
> tags are human readable as well.
>
> In my real life, I am forced to provide a software doku based on doxygen.
> This has pushed documentation level a lot. But from my experience no one
> reads the doxygen output itselfe, but if you read the code, you are happy
> to find the doxygen doku inline.
> The doxygen parser helps to find outdated docu and doku errors.
>
> So +1 for a doxygen, but -1 for add comments to different files.
>
> Kind regards,
>
> Daniel
>
>
>
>
>
> Am 03.01.2015 um 19:39 schrieb Ferran Pujol Camins:
>
> I'm missing code documentation for Mixxx. I understand that flooding
> source or header files with formatted comments will annoy almost everyone,
> so I've quickly set-up doxygen to read the source code as-is and then also
> read special *.doxydoc files placed away from the source code in a separate
> folder.
> This special files are nothing more than a copy of the header files with
> additional doxygen comments.
>
> This works pretty well and could allow everyone who wishes to document
> Mixxx's code while keeping source and header files clean from annoying text.
>
> Would you like something like this to be pushed to mixxx's trunk? Would
> you prefer QDoc, Doxygen or some other documentation tool?
>
> Kind regards, Ferran.
>
>
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming! The Go Parallel Website,
> sponsored by Intel and developed in partnership with Slashdot Media, is your
> hub for all things parallel software development, from weekly thought
> leadership blogs to news, videos, case studies, tutorials and more. Take a
> look and join the conversation now. http://goparallel.sourceforge.net
>
>
>
> _______________________________________________
> Get Mixxx, the #1 Free MP3 DJ Mixing software Todayhttp://mixxx.org
>
>
> Mixxx-devel mailing
> listMixxx-devel@lists.sourceforge.nethttps://lists.sourceforge.net/lists/listinfo/mixxx-devel
>
>
>
>
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming! The Go Parallel Website,
> sponsored by Intel and developed in partnership with Slashdot Media, is
> your
> hub for all things parallel software development, from weekly thought
> leadership blogs to news, videos, case studies, tutorials and more. Take a
> look and join the conversation now. http://goparallel.sourceforge.net
> _______________________________________________
> Get Mixxx, the #1 Free MP3 DJ Mixing software Today
> http://mixxx.org
>
>
> Mixxx-devel mailing list
> Mixxx-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/mixxx-devel
>
------------------------------------------------------------------------------
Dive into the World of Parallel Programming! The Go Parallel Website,
sponsored by Intel and developed in partnership with Slashdot Media, is your
hub for all things parallel software development, from weekly thought
leadership blogs to news, videos, case studies, tutorials and more. Take a
look and join the conversation now. http://goparallel.sourceforge.net
_______________________________________________
Get Mixxx, the #1 Free MP3 DJ Mixing software Today
http://mixxx.org
Mixxx-devel mailing list
Mixxx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/mixxx-devel
