[Nut-upsdev] [nut] High level C and C++ libnutclient (#2)

[Arnaud Quette]

2012/10/12 Emilien Kia <kiae.dev at gmail.com>

> 2012/10/12 Charles Lepple <clepple at gmail.com>:
> > https://github.com/clepple/nut/pull/2#issuecomment-9356397
> >
> > same comment from before still stands:
> >
> > [I took the liberty of replying on nut-upsdev - not many people are
> using github yet since the NUT repository native format is still SVN.]
>

you did well.


> > Also, "pull requests" don't really make much sense when we are still
> committing back to SVN, either. With git-svn, we can't do arbitrary merges
> - we can only rebase and run "git svn dcommit", which flattens out the
> repository history. Github assumes you are running a native Git repository,
> so closing a pull request doesn't make it clear whether or not the code has
> been merged.
> >
>
> Agree, but it helps to track code to merge.
>

and to prepare the future transition to git, and a possible external use of
github...


> >> @balooloo : I would however like to see some documentation. Strange
> that you missed that!
> >> The right place to insert this is 8.2 (after C/C++, before Python)
> >
> > 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.
> >
>
> Agree too.
> I can write a little paragraph to talk about this lib (in C/C++ sub
> chapter)


I'm really in favor of a dedicated chapter, Ie 1 for libupsclient and 1 for
libnutclient:

8. Creating new client
8.1. C / C++, using libupsclient (low level API)
8.2. C / C++, using libnutclient (high level API)
8.3. Python
...

but I think writing man pages is not really efficient due to
> the API size (in term of function number). IMHO a doxygen like
> documentation is more relevant. I will work on that, but perhaps the
> merge can be done without this.
>

I agree with Charles that manpage doc is useful, and part of our (NUT)
documentation approach (as for libupsclient).
Though my stance is that it's probably only suitable for C, not C++.

instead of created a manpage per function, you may create aliased manpages.
Ie 1 manpage for all the C interface, or 1 manpage per coherent block.

Doxygen is still a point to dig again, for the developer doc completion.
and this will probably be more suitable for C++.

> At the very least, the code in hazelnut can be cited as an example of how
> to use libnutclient.
> >
>
> Why not, but this code will increase and, as it uses UI lib, it is not
> really easy to understand.
> I am working on a little C++ program using libnutclient which query
> upsd and dump results in csv file. This is probably a better example
> of what it can do and how to use it.
>

2nded, for the same reasons.


> > - a pkg-config support file
>
> That is commited.
>

counter-checked. works for me.

Emilien: don't hesitate to tell me if you need some help on the Asciidoc
chapter + manpage.

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/20121012/61862ec4/attachment.html>