Using plsqldoc w/ non-standard standards?

[Stew Stryker]

I just started seriously trying out the plsqldoc plug-in. I like it well enough that I'll start adding the custom tags to my code.

But the vast majority of our code puts the comments for a procedure after the header. For one reason, I've found that the line numbers from the compiler errors ignore any comment lines before the procedure/function/package header. So it makes it easier to debug with comments inside, like this comment inside a packaged procedure.

PROCEDURE load_pf_group
    IS
        /*  Purpose : Populate pf_group collection for DCF Parent table, store by parent's ID
            Author  : STEWART_L_STRYKER
            Created : 08-Oct-2004 5:15:48 PM

            CS-RCS Modification History: (Do NOT edit manually)

            $Log: header.pkb,v $
            Revision 1.8  2005-01-26 17:13:50-05  stewart_l_stryker
            Added forward declaration

        */
etc...

My question is, how can plsqldoc determine this correctly, instead of assuming comments are before the header? The way it works now, the above comment for a packaged procedure would be added to the procedure following the correct one.

Any thoughts? Or am I going to need to edit them all to get this to work?

Thanks,

 

[D.]

I would put the comments before the procedure declaration in the package spec to allow plsqldoc to pick it up. Leave it like this in the body, if you like, to aid debugging. Although if you use PLSD to do your compilation, it should give you the exact line of error anyway.

Point to note though, putting large comments like this in your code will be getting inserted into the code in the database, clogging up the library cache. Especially if you start creating major comments in there about what was changed and when. I've seen many a package with megabytes worth of comments at the start just showing change history. Better to comment outside the procedure name, then it will be ignored at compilation.

Just my opinion,
D.

 

[Marco Kalter]

At the moment you must add the comment before the function/procedure declaration. Maybe we can make this a bit more intelligent though, and support the comment within the declaration as well.

 

[William Robertson]

I notice a lot of the Oracle supplied packages place comments below each item (e.g. DBMS_ALERT), although others place them above (e.g. DBMS_METADATA). Typical huh. It's a pity because it would be neat to generate plsqldocs for the lot in one go.

putting large comments like this in your code will be getting inserted into the code in the database, clogging up the library cache.

I would expect the compiler to strip out the comments from PL/SQL code (though not SQL).

I just tested this in 9.2 and 10.1 by creating a dummy package with and wiithout a large comment block and querying DBA_OBJECT_SIZE. The size was the same with and without the comments, unless I put them inside an SQL statement. I'm assuming DBA_OBJECT_SIZE gives an indication of how much space a package takes in the shared pool. Therefore I don't think you should worry too much about comments creating an overhead - though I agree that a complete change history that you have to scroll down through in order to see the code could become a PITA. I like to leave change comments in the version control application, and just put "what it's for", "how it works", "why I did this" type of comments in the code.

 

[Cornell]

FYI, the source lines are stored, as is, as seen in view SYS.ALL_SOURCE