6 Replies Latest reply on Feb 13, 2018 9:52 AM by B.Delmée

    db doc supported markup conventions ?

    B.Delmée

      I could not find much in the documentation about what is happening when clicking "generate db doc" from  a connection's contextual menu (particularly for PL/SQL code)

      To generate documentation in HTML format (comparable to Javadoc for Java classes) about a schema, right-click the connection name in the Connections navigator display and select Generate DB Doc. To view the generated documentation, open the index.html file in the output directory that you specified.

      Is the full set of markup conventions from the  pldoc project supported ?   If not, what is ?

        • 1. Re: db doc supported markup conventions ?
          thatJeffSmith-Oracle

          >>Is the full set of markup conventions from the  pldoc project supported ?

          They should be. If you see otherwise, let us know.

          1 person found this helpful
          • 2. Re: db doc supported markup conventions ?
            B.Delmée

            I'll do some tests - one limitation i noticed is one can only document objects from the connection's schema; it would be nice to be able to extend the selection as for the "export db" feature

            • 3. Re: db doc supported markup conventions ?
              thatJeffSmith-Oracle

              maybe you're using the wrong tool - have you seen what the modeler can generate for db documentation?

               

              the schema doc is designed for a single schema in mind

              • 4. Re: db doc supported markup conventions ?
                B.Delmée

                > maybe you're using the wrong tool - have you seen what the modeler can generate for db documentation?

                 

                alright, how should i go about it ?

                i am basically interested in generating the pldoc for a bunch of hand-picked packages (using a connection that can browse everything)

                 

                I tried importing a single package and could not figure out how to generate the db doc from the resulting model

                 

                > the schema doc is designed for a single schema in mind

                 

                was it always that way ?  i seem to recall having to wait forever  while it generated html for a whole db (probably still in 3.x)

                • 5. Re: db doc supported markup conventions ?
                  thatJeffSmith-Oracle

                  >>could not figure out how to generate the db doc from the resulting model

                  there are various reporting options available, which one did you try?

                   

                  it doesn't support the PL/Doc feature

                  • 6. Re: db doc supported markup conventions ?
                    B.Delmée

                    Two little glitches I noticed:

                     

                    when hitting <Ctrl><Space> above a procedure specification, sqldeveloper generates a comment skeleton which is very helpful, yet

                    • @param (and @return) annotations are injected in upper-case, whereas the help generator expects lower-case (and chokes on upper-case). Maybe this is influenced by a preference being set for upper-case SQL keywords but it shouldn't
                    • the generated block comment does not start every line with a star, which causes problems when deploying a package through sql*plus (which looks for param.sql and return.sql)

                     

                    in other words we get the following

                      /*

                      

                          @PARAM p_some_parameter VARCHAR2

                          @RETURN

                          */

                    while this would be better

                      /**

                       *

                       *   @param p_some_parameter VARCHAR2

                       *   @return

                       */

                     

                    It also seems that when a parameter is documented with several lines, sometimes they are retained and sometimes only the first one is kept in the generated html.

                     

                    Thanks!