Welcome to Open Discussion
Status: Alpha
Brought to you by:
altumano
Menu
▾
▴
Welcome to Open Discussion
Hi. Not much activity here yet.
We have an immediate need for PL/SQL inline documentation automation. I'm thinking something like XML tags that an XML parser can chug through. It'd be nice if we could use the same items for ColdFusion source code as well. Our web apps use CF on the frontend and PL/SQL on the backend.
We haven't started development yet for this new project I'm on. We're in the design phase. Now would be a good time to incorporate into our coding standards at least a first cut for an inline doc standard.
What have you done so far?
Dan Clamage
danielj@clamage.com
Hi,
sorry, I forgot to monitor that forum.
Last month this project did not get very far,
but now I can spend more time on this.
In addition, I have received feedback from another developer, who has developed Python version of that tool. This tool is not yet complete, but can generate docs for PL/SQL package specification, if advanced constructs like records and PL/SQL tables are not used.
Maybe we'll put that code on the project page, either as replacement or addition of existing Java version.
Tags we are planning to use are very similar to JavaDoc standard:
/**
* Comment line 1
* Comment line 2
*
* tags;
*/
Where tags are:
@author Authors name.
deprecated Obsolete subprograms.
@version Version of subprogram.
@param Parameter comment(e.g., @param xyz Holds XYZ name.)
@return Return parameter comment.
@see Reference other subprograms by links.
etc.
Albert.
P.S. Search google.com for "ColdFusion javadoc".
(I am one of those who proposed the Python version)
What kind of constructs did you try to parse?
I myself make use of records and tables, and they are correctly documented.
But I agree there are many lacks in the grammar...
Amaury,
Is the python version available somewhere? I'd like to give it a try.
- Dan Clamage
I was wondering if you ever thought of maybe emulating the perldoc application used in perl. I am currently working on a server side Oracle Procedure to act similar to Plerldoc. What I am doing is reading out of the user_source of all_source tables on the database which hold's all of the source. I will post my current ideas and example code on my site at www.mikomi.org/~hap/plsdoc/ . Take a look at it and tell me what you think. If you haven't used the perldoc in perl a breif run down on how it works. You place pod= and cut= (along with others) tags in you actual code and write up your comments and examples. When you do a "perldoc foo.pl" it will only show you the formated comments. What I am doing in PL/Sql will do the same in a sql*plus session.
Adam Hapworth
No, I really didn't know anything about perldoc utility.
Honestly, I like the javadoc tag format much more than that of Perl. It's more compact and easier to read. Also, it is more widely known and used.
But as much as I can see from your example, perl tags are much easier to parse. Actually, no parsing needed at all, just extract.
I wish you good luck doing the stuff, it's an interesting fresh idea.
This thing looks cool to me. I had a look at the source code so if I understand it right, pldoc parses the DDL to produce XML, then transforming it to HTML via XSLT. The XML part is interesting to me because generating the docs is one (very good) thing; but I could imagine doing even more. Let's use the perldoc example above: Why not generating perl wrappers (including the documentation) from the XML produced by pldoc?
What I like about parsing the PL/SQL source code in opposite to querying the database is that for the former I don't need a running Oracle instance.
So from my point of view it would make sense to spend some time on implementing "pldocs" for procedures/functions, types and exceptions. As soon as the parser is able to produce a "complete" XML representation of packages, procedures, functions, types and exceptions (and ...) we could do many more nice things with that data.
If you mean to generate formal comment from the XML, it is possible. But those comments would contain only names of the parameters. The real challenge is the extracting of existing (informal-style) comments near the parameters.
Concerning the "complete" PL/SQL parser:
ideally, it would be a separate open-source project. If this is done, many-many related tools could be created using the parser: formatters, code analyzers, impact analysis tools etc, etc.
The current parser developed for PLDoc is quite weak and has some ugly shortcuts inside, just to make it work as much as needed. But there is nothing fundamentally wrong with the parser (I hope), and it can be enhanced to become a "complete" parser.