2 Replies Latest reply on Aug 21, 2014 5:48 PM by Mike Kutz

    Is there a way to easily add PLDOC stubs to existing Packages?

    Mike Kutz

      Is there a way to quickly add PLDoc stubs to my existing packages?

       

      Right now, I'd be satisfied with just quickly adding the name and parameter list.

       

      Thanks

       

      MK

       

      example from

      create or replace
      package my_package
      as
        procedure proc_x( p_1 in int, p_2 in varchar2, p_3 in date );
      end;
      

       

      to

      create or replace
      package my_package
      as
        /**
        * my_package
        *
        * Lorem ipsum dolor sit amet
        *
        * @headcom
        */
        
        /**
        * description for PROC_X goes here
        *
        * @param p_1                   lorem ipsum p_1
        * @param p_2                   lorem ipsum p_2
        * @param p_3                   lorem ipsum p_3
        */
        procedure proc_x( p_1 in int, p_2 in varchar2, p_3 in date );
      end;
      
        • 1. Re: Is there a way to easily add PLDOC stubs to existing Packages?

          Is there a way to quickly add PLDoc stubs to my existing packages?

          Sql Developer has no such functionality that I am aware of.

           

          Oracle also doesn't provide reference info for the methods inside a package body.

           

          You could try writing a simple script to 'describe' your packages/functions/procedures. For packages it will use the SPEC information.

          SQL> desc my_package
          PROCEDURE MY_STORED_PROCEDURE
          Argument Name                  Type                    In/Out Default?
          ------------------------------ ----------------------- ------ --------
          OUT_VALUE                      MY_COLLECTION           OUT
          PROCEDURE MY_STORED_PROCEDURE1
          Argument Name                  Type                    In/Out Default?
          ------------------------------ ----------------------- ------ --------
          OUT_VALUE                      MY_COLLECTION           OUT
          P_COUNT                        NUMBER                  IN

          SQL>

          That method might get you started.

           

          I don't see much value in adding that infomation to ALL of the existing code if you have a large code base since it adds no value to what can be seen by simply looking at the spec or function prototype

           

          The information that is usually missing, and IMHO is the most important, is documentation that says what the code is SUPPOSED to be doing. No automated tool will be able to add that info for you.

           

          I suggest that your org discuss and adopt a simple standard to begin documentation for NEW code and/or when modifications of existing code are performed.

           

          That documentation should include at least a one line comment for any query or code block that isn't easily understandable.

          • 2. Re: Is there a way to easily add PLDOC stubs to existing Packages?
            Mike Kutz

            rp0428,

            I'm just trying to improve the the documentation for the Package Specs.

            The goal is to easily generate HTML documentation (maybe even PDFs) for future developers.

             

            Yes, I have comments in the Package Bodies.

            (Some are better commented than others.)

             

            rp0428 wrote:

             

            You could try writing a simple script to 'describe' your packages/functions/procedures. For packages it will use the SPEC information.

            SQL> desc my_package
            PROCEDURE MY_STORED_PROCEDURE
            Argument Name                  Type                    In/Out Default?
            ------------------------------ ----------------------- ------ --------
            OUT_VALUE                      MY_COLLECTION           OUT
            PROCEDURE MY_STORED_PROCEDURE1
            Argument Name                  Type                    In/Out Default?
            ------------------------------ ----------------------- ------ --------
            OUT_VALUE                      MY_COLLECTION           OUT
            P_COUNT                        NUMBER                  IN

            SQL>

            That method might get you started.

             

            Hmm..taking the results of an SQL SELECT statement, turn them into the "required" string, and display that string in an format that's easy to copy+paste.....

            That sounds like a job for an APEX Application...

            (The Specs already have a lot of comments in them.  I'm just trying to get them to be more PLDoc friendly.)

             

            MK