[Nut-upsdev] Nut-upsdev Digest, Vol 88, Issue 22

[VaclavKrpec at Eaton.com]

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 
-----------------------------