VaclavKrpec at Eaton.com
2012-Oct-29 08:53 UTC
[Nut-upsdev] Nut-upsdev Digest, Vol 88, Issue 22
?Hello everybody, just a few notes to the doxygen X man issue: 1/ AFAIK doxygen can generate man pages, so why don't we just generate them and decide then whether they are ill fitted or usable... 2/ I'd definitely use doxygen when possible; I mean I don't know any alternative that's able to do (at least partial) validation of the documentation with the source 3/ I have some experience with using doxygen for C++ code documentation and must warn you that there may be a need for some sacrifices; doxygen only does (quite poor) syntax analysis and is more C-suited; with certain C++ constructs, it fails quite flagrantly (at least the version I've used), an example being instantiation of a static object with global visibility scope, using constructor with arguments, e.g. something like this: MyClass my_var(arg1, arg2); doxygen misinterprets this as declaration of a function and requires you to document the parameters (you need to get rid of that using \cond and therefore you loose the possibility of documenting the variable). However, it's still the best I know. vasek On Sat, 2012-10-27 at 12:00 +0000, nut-upsdev-request at lists.alioth.debian.org wrote:> Send Nut-upsdev mailing list submissions to > nut-upsdev at lists.alioth.debian.org > > To subscribe or unsubscribe via the World Wide Web, visit > http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev > or, via email, send a message with subject or body 'help' to > nut-upsdev-request at lists.alioth.debian.org > > You can reach the person managing the list at > nut-upsdev-owner at lists.alioth.debian.org > > When replying, please edit your Subject line so it is more specific > than "Re: Contents of Nut-upsdev digest..." > > > Today's Topics: > > 1. Re: [nut] High level C and C++ libnutclient (#2) (Emilien Kia) > 2. Re: [nut] High level C and C++ libnutclient (#2) (Arnaud Quette) > > > ---------------------------------------------------------------------- > > Message: 1 > Date: Fri, 26 Oct 2012 14:13:59 +0200 > From: Emilien Kia <kiae.dev at gmail.com> > To: Arnaud Quette <aquette.dev at gmail.com>, Charles Lepple > <clepple at gmail.com>, nut-upsdev at lists.alioth.debian.org > Subject: Re: [Nut-upsdev] [nut] High level C and C++ libnutclient (#2) > Message-ID: > <CA+kuN+KvpoE-WGXiHhAkTOMf250ma5n8JzXNhHw66LAhkDdTFQ at mail.gmail.com> > Content-Type: text/plain; charset=UTF-8 > > Hi all, > > >> 2012/10/12 Charles Lepple <clepple at gmail.com>: > >>> https://github.com/clepple/nut/pull/2#issuecomment-9356397 > >> > >> In my mind, this is the biggest roadblock to merging. Developers need to > >> know that this library exists (News section of website, etc.) and need to > >> know why they might want this over the existing C API. Then, they need to > >> know how to use it. Much of the benefit of a wrapper library evaporates if a > >> developer has to basically read through the code to understand how to use > >> it. > > I have commited a little description of the new libnutclient with a > little code sample. > > I continue to think that manpages are not adapted to C++ documentation > and javadoc/doxygen-like is more adapted. > I will look at doxygen documentation generation when trunk will have > documentated code (and libnutclient have). > > Regards > > Emilien > > > > ------------------------------ > > Message: 2 > Date: Fri, 26 Oct 2012 19:59:26 +0200 > From: Arnaud Quette <aquette.dev at gmail.com> > To: Emilien Kia <kiae.dev at gmail.com> > Cc: nut-upsdev at lists.alioth.debian.org > Subject: Re: [Nut-upsdev] [nut] High level C and C++ libnutclient (#2) > Message-ID: > <CAFm_bUgrC4z=J9pMEoj4qEDEJO6pmkLKjV6o8uqOR-RDAEyPmw at mail.gmail.com> > Content-Type: text/plain; charset="utf-8" > > 2012/10/26 Emilien Kia <kiae.dev at gmail.com> > > > Hi all, > > > > Hi Emilien, > > >> 2012/10/12 Charles Lepple <clepple at gmail.com>: > > >>> https://github.com/clepple/nut/pull/2#issuecomment-9356397 > > >> > > >> In my mind, this is the biggest roadblock to merging. Developers need to > > >> know that this library exists (News section of website, etc.) and need > > to > > >> know why they might want this over the existing C API. Then, they need > > to > > >> know how to use it. Much of the benefit of a wrapper library evaporates > > if a > > >> developer has to basically read through the code to understand how to > > use > > >> it. > > > > I have commited a little description of the new libnutclient with a > > little code sample. > > > > great, thanks! > > I continue to think that manpages are not adapted to C++ documentation > > and javadoc/doxygen-like is more adapted. > > > > so we continue to be on the same page ;) > iirc, I only mentioned manpages for the C interface, not the C++ one (maybe > just over a coffee...) > > > > I will look at doxygen documentation generation when trunk will have > > documentated code (and libnutclient have). > > > > imho, this is a chicken-n-egg issue. > as for unit tests, the best is probably to have something showcased on a > branch, then merge that in the trunk and generalize to the whole tree... > and libnutclient would be a good opportunity ;) > > I'd be happy to help on this topic too... > I know Charles is also interested in, but he's already quite busy with git, > apcupsd-ups and real-life. > so he may just comment and give some thoughts. > > cheers, > Arnaud-- V?clav Krpec Network UPS Tools project Eaton Opensource Team ----------------------------- Eaton Elektrotechnika s.r.o. ~ S?dlo spolecnosti, jak je zaps?no v rejstr?ku: Kom?rovsk? 2406, Praha 9 - Horn? Pocernice, 193 00, Cesk? Republika ~ Jm?no, m?sto, kde byla spolecnost zaregistrov?na: Praha ~ Identifikacn? c?slo (ICO): 498 11 894 -----------------------------
2012/10/29 <VaclavKrpec at eaton.com>> Hello everybody, >Hi Vasek> just a few notes to the doxygen X man issue: > > 1/ AFAIK doxygen can generate man pages, so why don't > we just generate them and decide then whether they > are ill fitted or usable... > > 2/ I'd definitely use doxygen when possible; I mean I don't > know any alternative that's able to do (at least partial) > validation of the documentation with the source > > 3/ I have some experience with using doxygen for C++ code > documentation and must warn you that there may be a need > for some sacrifices; doxygen only does (quite poor) syntax > analysis and is more C-suited; with certain C++ constructs, > it fails quite flagrantly (at least the version I've used), > an example being instantiation of a static object with > global visibility scope, using constructor with arguments, > e.g. something like this: > > MyClass my_var(arg1, arg2); > > doxygen misinterprets this as declaration of a function > and requires you to document the parameters (you need to > get rid of that using \cond and therefore you loose > the possibility of documenting the variable). > However, it's still the best I know. >thanks for your comments. we are still trying to evaluate the best tool for documenting source code. Note that, as told, manpage are limited to C functions. as you say, doxygen is probably the best of bread. what would be very nice is a bridge between doxy and asciidoc... though I've not searched around that. I see doxygen limited to documenting the core functions (for maintenance purposes) and client APIs. cheers Arnaud -- Linux / Unix / Opensource Engineering Expert - Eaton - http://opensource.eaton.com Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org Debian Developer - http://www.debian.org Free Software Developer - http://arnaud.quette.fr -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20121029/5eaeb6db/attachment.html>