doxygen and rebranding update

[Pete Batard]

On 2012.04.04 00:00, Xiaofan Chen wrote:
>> The fact that libusbx is a replacement for libusb should be answered on the
>> main webpage, not in the API doc. But I think the API doc needs to mention
>> that switching from libusb 1.0.8 to libusbx is meant to be trivial, as
>> existing API calls and structures have not been modified.
>
> The main page is not enough. I would put it in the Doxygen Introduction
> and README file.

I disagree. Duplicating information right and left IS asking for trouble 
when it gets out of sync, which it always eventually does. We don't have 
much choice but to repeat some of the information between the README and 
web, but I'm hoping we can stop the duplication there.

IMO, because it's generated from the code, which we should try to keep 
lean (avoids bloat, which in turn avoids missing problems that are 
obscured by the bloat), we should not place too much of what we can 
place elsewhere into doxygen. Instead, I think doygen should indeed 
limit itself as much as possible to documenting the API. This is the 
very reason of existence of doxygen: place the documentation for an API 
along with the API itself, so that doc and API don't get out of sync.

> The first question users ask is "what is libusbx"?
> The first several questions distro packagers ask will be like these.
>     What is libusbx?
>     What are the advantages compared to libusb?
>     Can I package libusbx and libusb-1.0 together?
>     What about libusb-compat?

I've just updated the main wiki page, these would be good to get 
answered there. If you want to go for it, please do so.

> BTW, README should add Ludovic's name.
> http://libusbx.git.sourceforge.net/git/gitweb.cgi?p=libusbx/libusbx;a=blob;f=README;hb=HEAD

Will fix that, unless Ludovic doesn't want to see his e-mail be made 
readily available in the README. The implication of having your name and 
e-mail in the README is that, while not encouraged, it is possible that 
people will try to contact you for support or other requests if they 
feel like it.

> The Doxygen file is not only API documentation, but also some other
> stuff.

As explained above, while it most certainly can be used for more than 
just APIs, I disagree with doing so, as I only anticipate duplicate and 
syncproblems if we do.

> http://libusb.sourceforge.net/api-1.0/
> libusb-1.0 API Reference is rather a misnomer and I would call our
> libusbx doxygen documentation "libusbx documentation".

Well, the issue is that when we release 2.0, which is expected to have 
an incompatible API, we will need to have 2 concurrent versions of our 
APIs up for consultation. For instance one will (hopefully) use poll 
abstraction while the other will use the old poll.

Doxygen will be no help in trying to provide both at once.

> I think Travis does a good job for the libusbK Doxygen and libusbx
> can learn something from that.
> http://libusbk.sourceforge.net/UsbK3/index.html

Doubt we'll have much time to improve on simply trying to provide the 
basics (wiki, doxygen portal page, versioning, hopefully Windows binary 
snapshots) between now and 2012.04.16.

Doesn't mean that we shouldn't learn from what Travis did, but I'd like 
to use this opportunity to just remind everybody of being very mindful 
of our timeline, especially if requesting tasks to be performed that you 
are not planning to do yourself, as all of these add up and time is 
usually in much shorter supply than one may think.

This being said, if anybody wants to send in patches to improve the 
sources for doxygen or other stuff, feel free to do so. But as far as 
I'm concerned, I'm not planning to spend more time on doxygen than what 
I have done today - realistically, I just won't have time for that.

Regards,

/Pete