On Wed, Feb 4, 2015 at 10:16 AM, Justin Ross <justin.r...@gmail.com> wrote:
> On Thu, Jan 29, 2015 at 12:08 PM, Rafael Schloming <r...@alum.mit.edu> > wrote: > > > On Thu, Jan 29, 2015 at 9:28 AM, Justin Ross <justin.r...@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. > > Yeah, some of that is just left over from early days. I know of a few other examples from some dark corners. There's also a general pattern that doesn't quite fit. With the attachments stuff you can basically extend core objects with additional attributes. The reactor does this, for example to attach scoped handlers to endpoints, as well as to associate events with the reactor itself. The natural API for this sort of thing is to simply have pn_event_reactor(event) -> pn_reactor_t, however it would mess with the dependencies to actually define this where we define the other pn_event_ symbols, so it is defined in reactor.h. > > 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 like this. I didn't know you could do this. What's the appropriate markup to make doxygen aware of the class/member relationship? - 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? > - 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. > 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. Something to be aware of here is that my thinking on the need for multiple reactors has changed a bit. I wrote a separate post about it since it got a little lengthy to incude here, but the upshot is that the API layout doesn't necessarily need to accommodate multiple completely distinct reactors in the way that we previously had imagined, and that it may be worth featuring the base reactor a little bit more prominently. --Rafael
