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, [email protected] wrote: > Send Nut-upsdev mailing list submissions to > [email protected] > > 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 > [email protected] > > You can reach the person managing the list at > [email protected] > > 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 <[email protected]> > To: Arnaud Quette <[email protected]>, Charles Lepple > <[email protected]>, [email protected] > Subject: Re: [Nut-upsdev] [nut] High level C and C++ libnutclient (#2) > Message-ID: > <ca+kun+kvpoe-wgxihhaktomf250ma5n8jzxnhhw66lahkdd...@mail.gmail.com> > Content-Type: text/plain; charset=UTF-8 > > Hi all, > > >> 2012/10/12 Charles Lepple <[email protected]>: > >>> 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 <[email protected]> > To: Emilien Kia <[email protected]> > Cc: [email protected] > Subject: Re: [Nut-upsdev] [nut] High level C and C++ libnutclient (#2) > Message-ID: > <CAFm_bUgrC4z=j9pmeoj4qedejo6pmklkjv6o8uqor-rdaey...@mail.gmail.com> > Content-Type: text/plain; charset="utf-8" > > 2012/10/26 Emilien Kia <[email protected]> > > > Hi all, > > > > Hi Emilien, > > >> 2012/10/12 Charles Lepple <[email protected]>: > > >>> 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 ----------------------------- _______________________________________________ Nut-upsdev mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev
