PL/SQL Doc, @ tag, and SQL-Plus

[jasonvogel]

Metalink posting : http://metalink.oracle.com/metalink...howDocument?p_database_id=FOR&p_id=411393.995

Background:

We use "set define off" at the top of our compiles. We have an automated batch process that compiles our source to Develoment and then is used to move the source to Production. It is a bunch of Unix scripts and SQL-Plus commandline.

Description:

If you use SQL-Plus [commandline] to compile your source, the lines that start with "@" or "#" flags [in your comments] will be "ignored" (example result: SP2-0310: unable to open file "Author.sql"). On the surface, this would seem fine except that SQL-Plus REMOVES the rest of the line from the COMPILED source! So then if you pull the source from the database...your PL/SQL Doc Comment Tags are gone!

The only way to get them to "stay" is to change the format to "--@Author ..." which is not supported by PL/SQL Doc.

So pull your source from version control system and never the DB or risk losing your tags.

Jason

 

[Marco Kalter]

Thanks for sharing this tip. We're considering to support the % sign for tags (%author). Hopefully current and future SQL*Plus versions will not try to interpret this character within a comment section.

 

[jasonvogel]

I'd definitely like to try the "%" approach, but I'd bet that would be a parsing mess for you guys given the %ROWTYPE, %TYPE, ... stuff.

Any idea how hard that would be?

Jason

 

[rbrooker]

suggestion :

why dont you make the documentation tags domething like "--%" or "--@" without the quotes?

this way, sql will think them a comment and only the plsql doc plugin will recognise them for something different.

 

[jasonvogel]

PL/SQL Doc doesn't support the -- prefix syntax...thus rendering my documentation useless.

Jason

 

[Marco Kalter]

I'd definitely like to try the "%" approach, but I'd bet that would be a parsing mess for you guys given the %ROWTYPE, %TYPE, ... stuff.

Any idea how hard that would be?

The plsqldoc Plug-In will only process the tags it knows. Whatever character we choose, it can always appear elsewhere in the source.