One of our more popular features is ‘DB Doc.’ It’s like JAVADOC for the database. Pick a connection, right-click, and go. It will generate an HTML documentation set for that schema.

For version 4, we’ve introduced a few enhancements based on user requests. That’s right, you asked, and we listened.

  1. Added support for Package Bodies
  2. Added parallelization option for larger doc sets
  3. Enhanced the HTML formatting a bit

Select Your Object Types and Generation Options

We've changed the default selection of object types to be included and added support for package bodies
We’ve changed the default selection of object types to be included and added support for package bodies

There’s also an option to auto-open the documentation set after it’s been generated.

And the HTML As Requested

And your documentation, as requested!
thatjeffsmith
Author

I'm a Master Product Manager at Oracle for Oracle SQL Developer. My mission is to help you and your company be more efficient with our database tools.

28 Comments

  1. Richard Lyders Reply

    Hi Jeff, Is there a way to run DB Doc via the command-line so that it can be automated?

    • Amaranatha

      Yes. It’s really important to have the facility to run this via command line. Please provide the information on this.

  2. Support for Package Bodies seems limited, the DOC itself is empty, only details, grants are filled. Most of the documentation written by programmers close to the code is not visible in the documentation, which is the whole point of having support for Package Bodies. Unless I missed something and generated the DB Doc wrong.

    • thatjeffsmith

      please provide examples of what’s not working…and usually the docs go in the package specs, but we added support for including the bodies in the v4 releases, so it should be working

  3. Martin Mierke Reply

    I also like the feature in general, but I always get an Error

    ERROR! String index out of range: -245

    in the Method Detail frame

    when I try to document a PACKAGE.

    Any ideas out there? Any help would be nice.

    Br Martin

  4. Etienne Gauthier Reply

    How can I generate the doc for a Type Body it doesn’t do it, why?

    Thanks

  5. Priya Kalidindi Reply

    Hi, Is there a plan to provide the option to pick the Database object that we want to generate documentation on? The reason I ask is, we are in an Oracle EBS environment and most of our custom packages reside in the main schema called APPS. (We have to have these packages reside in this schema so they can access many many API etc have synonyms in this schema only) This APPS schema is huge and it will be difficult(and not necessary) to get the documentation to be generated for the APPS schema.

    We really like the DBDOC feature and would love to use it for documentation. Please let me know if there is a plan to provide the option to pick some object and produce the documentation.

    Thank you,
    Vishnupriya

    • thatjeffsmith

      As a workaround you could just copy them over to a DOC schema, then just doc that schema – but for now, there are no plans for filtering. I’m guessing that most shops don’t put custom code in their APPS schema?

    • Priya kalidindi

      I agree that is a work around and I was thinking in the same line.

      Yes most shops put their packages and even views in the APPS schema because it is not possible to make synonyms to all the objects to a custom schema.
      We create all of our custom tables and packages that are for our 3rd party custom application that do not require APPS objects in a custom schema; in all the shops I worked the standard is for APPS related packages to be created in APPS schema (one place I worked we used Oracle on Demand and they had strict guidelines on CEMLI object creation and we are following similar framework)

    • I agree with Priya – it would be very useful to select individual objects to document. There are many instances where you must put custom code in the APPS schema. I would love to use this for a package I am developing, but don’t want to run this against everything in APPS.

    • David Grimberg

      As an alternative to creating DOC schema, the generate DB Doc functionality respects the filters applied to the connection tree (at least as of SQL Dev 4.1.2.20). As such you can filter the various nodes to just those objects you want documented. So there’s no need to create a custom documentation schema, but creating a separate documentation connection to your DB may be helpful.

      I too am in an EBS environment and it’s working for our custom code to apply connection level and/or object node level filters.

  6. Hello, Jeff! Thank you for an article. One minus is that the status of the generation process is unvisible if it is runnung in a background.

    • thatjeffsmith

      View > Task Progress.

      Once you set it to run in the background, the ‘Generating Documentation (Running)’ indicator will light up. You can also cancel it from here.

  7. Hi –
    Is it possible to select some packages, objects not all database objects to generate documentation.

    Regards,
    Omar

    • thatjeffsmith

      You can say ALL tables or NO tables, but not SOME tables.

      You have more flexibility in the Data Modeler reports though…you’d need to import a data dictionary to a new design/model and then export that out to HTML. It doesn’t pick up the DB DOC comments like this does though.

    • Hi –
      We are intending to use this in our documentation process for our database, and we are satisfied with PL/Doc comments. If a package has changed I have to generate DB DOC for all database packages, am I right. Is there any intention to add a filter before running DB DOC?.
      Regards,
      Omar

  8. Thank you for the fast reply.

    Could you please be more precise?
    Where can I find the “HTML reporting” functionality in the DataModeler?
    What have in common Data Modeler and DBDOC?

    Sorry for the so many question. I would like to better understand ;).
    I really appreciate your help.

    Cheers!
    Zere

    • thatjeffsmith

      You can generate data dictionary reports for your system using the modeler. One of the output formats is HTML.

  9. Hi Jeff,

    What about the customization of the output pages?
    Do you know if there is a way to customize the pages from the point of view of the CSS and the information to be shown?

    My users do not need to know about the GRANTS,DEPENDENCIES and CODE.

    Do you know which is the java class that is in charge of the generation of the documentation?

    Thank you in advance!
    Zere

    • thatjeffsmith

      The customization would need to be done via regex scripting by you.

      Depending on your needs, you might find the html reporting in Oracle SQL Developer Data Modeler more flexible and suitable to your needs.

  10. Nigel Richmond Reply

    Jeff

    Hopefully this isn’t a silly question – how do I use this to document objects in other schemas which I have access to, but don’t have the schema password for? Thanks

    • thatjeffsmith

      It’s NOT a silly question. Today we require a direct connection, so you’ll have to ask someone with access to generate the docs for you.

    • Nigel Richmond

      Thanks – is there any plans to whether this will be provided in the future?

  11. Mhmm seems my code snippet vanished 😕
    nsBIM140Entry

    insBIM140Entry( guid IN bim140 . guid % TYPE DEFAULT NULL , typ IN bim140 . typ % TYPE DEFAULT NULL , workspace IN bim140 . workspace % TYPE DEFAULT NULL , application_id IN bim140 . application_id % TYPE DEFAULT NULL , application_name IN bim140 . application_name % TYPE DEFAULT NULL , user_name IN bim140 . user_name % TYPE DEFAULT NULL , authentication_m IN bim140 . authentication_m % TYPE DEFAULT NULL , app_schema_owner IN bim140 . app_schema_owner % TYPE DEFAULT NULL , access_date IN bim140 . access_date % TYPE DEFAULT NULL , ip_address IN bim140 . ip_address % TYPE DEFAULT NULL , auth_result IN bim140 . auth_result % TYPE DEFAULT NULL , custom_stat_text IN bim140 . custom_stat_text % TYPE DEFAULT NULL , workspace_id IN bim140 . workspace_id % TYPE DEFAULT NULL , ersteditdat IN bim140 . ersteditdat % TYPE DEFAULT NULL , ersteditid IN bim140 . ersteditid % TYPE DEFAULT NULL , ltzteditdat IN bim140 . ltzteditdat % TYPE DEFAULT NULL , ltzteditid IN bim140 . ltzteditid % TYPE DEFAULT NULL ) RETURN BOOLEAN ;

  12. This looks great.
    But i would request some little enhancement on documenting package procedures/functions. look at the following entry:
    <<<<<<>>>>>>
    as you can see some page breaks would make the long parameter list a lot better readable. in the report all parameters are listed in one single line.

    there is a little issue with %TYPE definitions: the whitespaces between the separatores ” bim140 . ltzteditid % TYPE” are confusing.

    as we say in german “ist only jewelry on a nightgown”. the output is fantastic. i love it.
    Greetings
    Peter

  13. Jeff,

    This option looks fine. but when I thought to give a try, I don’t know where can I find “Generate db doc” option? picked up a package and table from sql-developer V4 schema browser I don’t see any option to generate db-doc. can you guide me?

Write A Comment