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. > 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.
