I hate gmail, sorry:
Personally I also prefer to have documentation comments in the code files
themselves but I wanted to remember there are alternatives, just in case
that was what pulled Mixxx's documentation back.
I've also agree that there's no point in providing a doxygen generated
documentation that just comes with code hierarchy visualization and minimum
comments. In fact, each developer can use an IDE or generate the
documentation by themselves like I do.
However, I do find some core parts of mixxx are complex enough to deserve a
higher view text explanation. So let me re-formulate my question: Suppose
we have some documentation tool that can read Mixxx's code as is now, and
can also read additional files where in depth textual explanation of some
specific parts of Mixxx is provided. Would you have any inconvenience to
include this with mixxx source?
I'd really like that, so if you don't mind I'll investigate a bit more
about it. Otherwise I'll let it go.
2015-01-03 21:45 GMT+01:00 Ferran Pujol Camins <ferranpujolcam...@gmail.com>
:
> Sorry, ignore previous incomplete mail:
>
> 2015-01-03 21:44 GMT+01:00 Ferran Pujol Camins <
> ferranpujolcam...@gmail.com>:
>
>> Personally I also prefer to have documentation comments in the code files
>> themselves but I wanted to remember there are alternatives, just in case
>> that was what pulled Mixxx's documentation back.
>>
>> I've also agree that there's no point in providing a doxygen generated
>> documentation that just comes with code hierarchy visualization and minimum
>> comments. In fact, each developer can use an IDE or generate the
>> documentation by themselves like I do.
>>
>> However, I do find some core parts of mixxx are complex enough to deserve
>> a higher view text explanation. So let me re-formulate my question: Suppose
>> we have some documentation tool that could read Mixxx's code as is now, and
>> can also read additional files where in depth textual explanation of some
>> specific parts of Mixxx
>>
>> 2015-01-03 21:06 GMT+01:00 RJ Ryan <russelljr...@gmail.com>:
>>
>>> 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
>>>
>>
>>
>>
>> --
>> Ferran Pujol Camins
>>
>
>
>
> --
> Ferran Pujol Camins
>
--
Ferran Pujol Camins
------------------------------------------------------------------------------
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
