qpid-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Justin Ross <justin.r...@gmail.com>
Subject Re: Proton API layout proposal
Date Wed, 04 Feb 2015 15:16:44 GMT
On Thu, Jan 29, 2015 at 12:08 PM, Rafael Schloming <rhs@alum.mit.edu> wrote:

> On Thu, Jan 29, 2015 at 9:28 AM, Justin Ross <justin.ross@gmail.com>
> wrote:
>
> > This makes good sense on its own, but it doesn't help with our goal of
> > naming and grouping together a "growable library of like things".  In
> other
> > words, if we end up with many reactor implementations, it won't be very
> > approachable to have them littered around as dissimilar peers to
> reactor.h.
> >
>
> I don't think it's really workable to think of C header files as simple
> analogs to python packages. C header files need to first and formost
> correspond to the C symbols they include. Breaking that correspondence does
> a huge disservice to the usability of the API from C. Beyond that, the fact
> that C doesn't actually have packages and has just one global namespace
> really forces you to use flatter naming for your C symbols since everytime
> you type a symbol, you need to type out its full global name. These two
> things together pretty much guarantee that the C header files can't match
> python package names unless you force everyone to type out the full python
> package name as part of every C symbol.
>
>
I take your point.  As you suggested, I've got a scheme that uses doxygen
to achieve the grouping goals I have in mind.

In line with your expressed intent here, and having poured over the
headers, I think there are a few instances where the symbol-to-header
correspondence could be tighter: pn_data_*, pn_logger_t, pn_collector_*.
In some instances, it seems like it would make sense to rename the symbol,
and in others to add a corresponding header.


> If you want to improve approachability, doxygen has lots of tools for
> defining groups and organizing/presenting otherwise flat APIs in a more
> structured way. This is because the whole large flat C API is pretty
> common, so generally it is organized with annotations in the doc tags that
> doxygen then uses to create things that actually are more analogous to
> python packages. This used to be set up, I'm not sure if it still is, but I
> would suggest that this is probably the first place to look to start
> improving accessibility.
>

Here's a first attempt:

  http://people.apache.org/~jross/proton-apidoc-draft/modules.html

To summarize the delta from the current docs:

  - The groups are a flat array; this relates to the next point of
difference

  - I used class-and-member relationships to achieve a grouping where it
applies; I think it applies quite a bit, and the resulting api doc is more
natural to me

  - I avoided bifurcating the API at the top level into engine and
messenger; instead I tried to treat everything as the "Proton API"

  - Where applicable, I used the groupings defined in the API layout
proposal; note that I have pn_reactor_* in the Event group--that's
something we talked about in our initial discussion of the API layout

I don't at all consider the api layout finalized, so if this effort points
up some problems, let's adjust.  The same of course goes for the C api doc.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message