An update. I've made a few changes to the api layout proposal:
https://cwiki.apache.org/confluence/display/qpid/Proton+API+layout+proposal - Renamed proton.reactors to proton.reactor - Added proton.security, to clean up the "core" space. This would be home to future additions such as message encryption as well. - Went with proton.extras over proton.contrib. This was to avoid any appearance that we are disowning the pieces there. Instead, they are simply extensions outside the core Proton functionality. Gordon also put forward the notion of proton.adapters in lieu of proton.extras. I like that as well, but I think it has a narrower sense, and I was aiming to keep the buckets bigger and flatter. The following is incomplete, but it at least previews the application of these groupings: http://people.apache.org/~jross/proton-apidoc-draft-2/modules.html Once I fill all this in, I intend to use the main page tab to explain each top-level group and tell the user what they need to focus on first. Justin On Wed, Feb 4, 2015 at 1:32 PM, Justin Ross <justin.r...@gmail.com> wrote: > > > On Wed, Feb 4, 2015 at 1:00 PM, Rafael Schloming <r...@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. > >
