[CREATE] [OpenRaster] libora: shallow review, thoughts

[Luka Čehovin]

Let me give a quick reply to your review.

On Fri, Oct 1, 2010 at 11:13 PM, Jon Nordby <jononor at gmail.com> wrote:
> I intend to implement library functionality that viewer-class
> applications can use to support OpenRaster. My focus will first be on
> a simple API for getting a pixelbuffer of the fully rendered image.
> Eventually good integration in existing GTK+ and Qt based applications
> is the goal. I'm hoping that I can do this by extending or building on
> top of libora, so I had a quick look at the code. Here is some
> feedback based on that.

Excellent! I will help where I can ... starting with this mail.

>
> - Generated code
> There is generated code in src/lib/layers/stack_parser.h
> It has a comment saying "Generated with genesx alpha", but I could
> find anything relevant on google. How is it generated? What is the
> license?

Ok, this is my mistake. "Genesx" is one of my numerous
experiments/small-projects. basically I wanted to create a system to
automatically generate a code for the expat xml parser (that is pretty
basic, but has no dependencies and it very portable). The license here
is what we want it to be i guess. I did some research back then
regarding xml parser generators but found none that would suit my
requirements. The generator is written in python and is not really
production rate code nor is it complete, but it works for the current
needs of the project (my opinion). I can publish the code somewhere.
The reason for using autogenerated code is that writing xml parsing
code is dull and error prone business. At the same time I am aware
that some of you may not like this solution so I have no problem with
somebody writing the parser/validator by hand.

>
> - Documentation
> There is no documentation. I'm missing high-level documentation for
> the library: purpose, scope, use-cases, design principles;
> and low level documentation of the code:
> file/function/datastructure/macro documentation and comments. For a
> start it needs enough docs that people (like me) are able to hack on
> or use it without having to read and understand the source for each
> and every function. Luka, since you wrote the code, can you please
> help out here?

No problem. From the beginning I planned to use Doxygen but as it
frequently turns out I got too immersed in the coding and forgot about
it :)
Since there is now immediate interest I will try to write some
documentation as soon as possible. Perhaps you can just tell me where
I should start (what is the most important part?)

>
> - API/ABI
> We want the library to be api/abi stable eventually. The current api
> is not good enough in that aspect, for instance read/write_layer uses
> a single positional argument for each layer attribute. This will break
> the second someone adds a new attribute, something that has actually
> already happened. There needs to be a more extensible way to handle
> this and similar things.
> I would welcome input from experienced library developers here.
>

Well everything started as a prototype. I would gladly change all the
functions in ora.h file (the idea is that this is the public
interface) so that we have a flexible API. At that time nobody showed
particular interest of using the library anytime soon so I did not
bother with a really flexible API. Perhaps a wiki brainstorming might
be a good place to start?

> There was also a lot of minor things, but that is of lesser importance
> at this stage.
>

Of course ... we can address all of them when needed.

cheers,
-- 
Luka Čehovin
http://luka.tnode.com