Ken already wrote a bunch of documentation on this, perhaps he could post a link?
Also, if you run 'make docs' you can see all the doxygen for the engine APIs. While I agree we need more documentation, keeping the C and Java impls in sync is a separate matter. Documentation as a functional spec is really only useful if it reaches the level of a formal specification that never changes, however that's just not realistic for us. Besides, we already have a much much more powerful tool for keeping the implementations in sync. We have the python test suite that will run against both implementations and tell us precisely where they differ. I really would like this test suite to be the formal spec, and like everything else it could certainly use more documentation, but it's quite capable of keeping the implementations in sync without that, and more importantly unlike a static document, we can drive changes in the functional spec that might be motivated by either the C or Java or JS impl back into this test suite and spread them to the other implementations much more quickly than we can with just a document. If there are problems with that model, or if the test suite is somehow insufficient, I'd really like to know. I know Rob has mentioned that the tests need to be more granular, some of them are a bit monolithic because they are trying to reproduce a very specific set of behaviour. For the new stuff I've been adding I've been trying to keep things as granular as possible. --Rafael On Thu, Sep 20, 2012 at 3:45 PM, Rajith Attapattu <[email protected]>wrote: > We should seriously consider documenting the Engine API and it's > expected behaviour. > This has several advantages. > > 1. Use that as a basis for a functional spec, which we can then write > tests to verify the implementations. > > 2. Helps developers to navigate and understand the code more easily. > > 3. Finally we need this documentation sooner than later to accompany > our releases to for the end users > > 4. Helps to keep both C and Java impls in sync. We should probably > modify the doc before we change the code to ensure the doc is kept > current. > > Any takers ? (Looking at Rafi :D) > > Regards, > > Rajith >
