Forum OpenACS Development: documentation style for data models

Posted by Rafael Calvo on
I have noticed that most posgres sql files contain the original oracle
code. This makes files twice as long, when the original code is anyway
kept somewhere. Is this the right style? Would it make sense to keep
only the titles?
Posted by Don Baccus on
I think this partly stems from Dan's use of scripts to do some of the mundane munging necessary to change from Oracle to Postgres (correct me if I'm wrong, Dan).

I'd vote for removing these stubs once the package is ported (or earlier if the developer doesn't find them useful).

Posted by Dan Wickstrom on
That's true.  I had the scripts set up to leave the package declaration section inline as comments, and I converted the package body to pg code.

I've also seen other code in openacs where the package body had been converted so that commented out versions of the oracle functions were left iterspersed with the pg equivalents.

I'm not sure which case Rafael is talking about, but in either case both versions of commenting could be excised from the pg code, as the oracle code still retains all of this information anyway.

One thing that I have found useful is to leave comments next to the function arguements that indicate what the default values should be.  This allows a developer to quickly look up the default arguements to a function when porting a module or doing new development.

Eventually, we might want to add javadoc style comments to the pg function headers, as there is already existing code to do introspection of pg/oracle db packages from  a web browser.  Some of the original oracle packages already support this, and I've experimented with making it work in pg, and I don't see any problems with it besides the fact that we'll have to go in and add all the comments.

Posted by Rafael Calvo on
I was looking at the notes package when I wrote the question, and the port of acs-events (that we haven't uploaded yet) and another package, that I couldn't find now. Anyway, you answered my question, thanks. I will remove all the stubs when finished (in fact, earlier since it is easier to have two emacs windows than the other embeded code)