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.
