Documenting DDL based VDB

[gadeyne.bram]

Hi,

Does anyone know if there are tools available to document SQL scripts? More specifically views and or procedures?

I'm wondering about both IDE support while writing a DDL based VDB and the possibility to extract some sort of vdb schema manual.

E.g.

/*
Does Something
@param a The magnificant parameter to do something with.
@return int Something
*/
CREATE VIRTUAL PROCEDURE DoSomething(a integer)
AS
BEGIN
     select a + 1;
END

That would result in the IDE describing "DoSomething" as "Does Something" and describe its parameters and return types.

Alternatively some sort of generator may exist that generates a "Javadoc" like overview of procedures, schema's, views, etc who are present (and documentated) in the VDB.

[rareddy]

I believe currently the DDL parser is ignoring the comments, but something like that is possible. Maybe a contribution? I do not know of any IDE for DDL that Teiid team developed.

[shawkins]

There are a couple of approaches here.  The first is that a description field is built into the metadata record.  You can set the annotation option - ... options (annotation 'something descriptive') - and it will be part of the actual metadata.  Documentation could easily then be generated from the system schema - without the need to do parsing.  The other approach as you have shown above is comment based, that would cut down on the amount of runtime information but would require some kind of parsing support which would be difficult as the javacc grammar file doesn't lend itself to extensions very easily.  It would likely take a whole change to allow for a customization of comment handling - but that would likely be at the token level.