I had the opportunity to sit down and design a C API for creating PureDocs Resource objects this weekend. For the C API, Resource is an opaque type, and the API provides the ability to create a Resource, add properties, children, etc, without having to worry about it being a Python type.
The reason behind C plugin support for an API documentation generation utility that parses files based on grammars should be pretty obvious. Because most higher-level languages, at the very least, have implementations in C, there are readily available parsers. Having to reinvent the wheel just because we're using Python, or at the very least, write Python-C support code, would be painful and reduce the usefulness of PureDocs. Having a simple C API that can be used to wrap one of these existing parsers seems to be the optimal situation.
The C API itself is defined in a library, libpuredocs, that links against Python to provide access to the Python data types. C plugins will be loadable modules linked against libpuredocs. They will be dyanmically loaded by PureDocs (perhaps by a C Python module) into the same address space, so that Resource objects ca easily be passed back and forth between PureDocs and the C plugin.
It took me a little while to come up with just the right way to do this to avoid C plugin authors having to have any interaction with Python at all. I still haven't figured out how loading and registration of C plugins will work, but I think the datatypes were the hard part. I'll write more about this once the entire thing is finalized. For testing purposes, I have passed a Resource object back and forth between a pure-C loadable module and a C python module, with success.
A quick test showing that Resource objects created using the libpuredocs library can be used in Python looks something like the following, implemented in C:
#include <Python.h>
#include <stdio.h>
#include "puredocs.h"
PyObject * test_function(PyObject * self, PyObject * args) {
Resource * r = puredocs_createResource("foo");
Resource * c = puredocs_createResource("bar");
puredocs_setDocString(r, "omg some docs lol");
puredocs_setDocString(c, "some bar docs omg lol");
puredocs_setProperty(r, "feh", "omg");
if ((puredocs_addChild(r, c)) < 0) {
printf("OH NOES!\n");
}
return (PyObject *)r;
}
The C API (along with the Python API) is documented in The PureDocs Plugin Architecture. Again, I'm going to provide more concrete examples once I have loading and registration worked out, and have some working C plugins as examples.