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 18:32:42 GMT
On Wed, Feb 4, 2015 at 1:00 PM, Rafael Schloming <rhs@alum.mit.edu> wrote:
>
> > 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 like this. I didn't know you could do this. What's the appropriate markup
> to make doxygen aware of the class/member relationship?
>

You put @class foo_t on the typedef and @memberof foo_t on the related
functions.  Once you've done that, the members fall in the group of the
class without being explicitly marked up for it.

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


>   - I avoided bifurcating the API at the top level into engine and
> > messenger; instead I tried to treat everything as the "Proton API"
> >
>
> I like avoiding the bifurcation. The one thing I think isn't so great about
> this is when you click on the Endpoint group you get a huge listing of
> stuff. It took me a couple of minutes to pick out the fact that the data
> structure stuff basically linked to "class scoped" documentation. I think
> in some ways the previous sub grouping scheme was a little better here
> since you could navigate straight to Connection/Session/Link/whatever from
> the modules page and just collapse those levels if you don't care about the
> sub groups. Is there a way to use the sub grouping along with the
> class-and-member stuff to get the best of both worlds?
>

I agree that the picture under endpoint is confusing.  I'll produce a few
alternatives.


> >   - 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
> >
>
> After actually using some of the APIs a bit, I'm wondering whether it
> doesn't make sense to have the group called reactor and feature the reactor
> more heavily as an entry point. This is because the reactor is the first
> thing you construct/interact with. In python you aren't really even aware
> of events as a first class thing, they just get passed into handlers and
> have useful stuff in them, but you never import or construct them directly.
> In C where you have types you do have to be a little bit more aware of
> them, but it's really a secondary thing after you have set up your reactor.
>

>From what I've seen in the C api, a reactor group would make more sense.

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