Results 1 to 4 of 4
  1. #1
    Digital Larry is offline Member
    Join Date
    Mar 2013
    Posts
    57
    Rep Power
    0

    Default Extracting different types of help from source code comments

    I already have used some "Javadoc" type comments and the help extractor to create API documentation for my code. I would also like to try to embed user documentation in parts of my code as well, and also link this semi-automagically within my program.

    I'll explain the context. My Java program is a CAD program where one assembles blocks on screen which ultimately form a functional DSP (digital signal processing) algorithm. Each one of these blocks is represented by a CADBlock class, which controls the details of the code generated, and optionally a ControlPanel class, which allows the user to pop up a dialog with sliders, checkboxes, etc. to adjust certain things within the CADBlock class.

    I want to be able to embed comments in one or the other of these classes that would be extracted to user-facing documentation and omit the API info that is already in the code. I would also think it was great if somehow the resulting LINK to that documentation could be embedded into the active code, so that the user could right-click on a block and select "Help" from a popup menu, then get sent to the relevant help page within a larger HTML structure.

    Anyone know of a tool or strategy that can do this? Note that I didn't ask which one was "the best". I just want to know if any exist at all!

  2. #2
    jashburn is offline Senior Member
    Join Date
    Feb 2014
    Posts
    219
    Rep Power
    1

    Default Re: Extracting different types of help from source code comments

    This is at least partially possible. Take a look at Doclet Overview for the way to create custom javadoc tags and command line options to generate custom docs. See also Doclet.com for examples of custom doclets that, e.g., creates DocBook XML from javadoc (using Docbook-Doclet, which you can then transform into any form you want such as HTML and PDF).

    I'm not sure how you might be able to embed documentation links into active code directly using javadoc. Perhaps XDoclet can help as it states on their web site, "It's a generic Java tool that lets you create custom Javadoc @tags and based on those @tags generate source code or other files (such as xml-ish deployment descriptors) using a template engine it provides."

    As documentation can be updated independently of code, maybe a better approach would be to externalise a Help ID-documentation link mapping file similar to the way UI text is externalised in Java using resource bundles. This way the Help IDs can be hardcoded into the right-click actions. You can then write a relatively simple framework to translate the Help ID to the corresponding documentation link to be brought up in a browser when a user selects Help from a block's right-click menu. You might be able to generate the mapping file using a custom doclet or XDoclet. Having an externalised mapping file would also help should your documentation need to be provided in multiple languages, now or in the future.

  3. #3
    JosAH's Avatar
    JosAH is offline Moderator
    Join Date
    Sep 2008
    Location
    Voorschoten, the Netherlands
    Posts
    13,662
    Blog Entries
    7
    Rep Power
    21

    Default Re: Extracting different types of help from source code comments

    Maybe the JavaHelp framework can be of any help here (or at least the mechanisms it uses).

    kind regards,

    Jos
    cenosillicaphobia: the fear for an empty beer glass

  4. #4
    Digital Larry is offline Member
    Join Date
    Mar 2013
    Posts
    57
    Rep Power
    0

    Default Re: Extracting different types of help from source code comments

    That is very interesting info - thanks for taking the time to write a response. I will certainly look into that, right after I get done shoving some more feature creep into the program.

Similar Threads

  1. Question regarding code format/style and comments
    By BustTheCode in forum New To Java
    Replies: 7
    Last Post: 09-27-2013, 09:06 AM
  2. Extracting comments
    By tauraus in forum Advanced Java
    Replies: 1
    Last Post: 04-27-2012, 01:22 PM
  3. Replies: 1
    Last Post: 11-28-2008, 06:27 PM
  4. How to write code comments
    By Java Tip in forum java.lang
    Replies: 0
    Last Post: 04-23-2008, 08:06 PM
  5. Comments in java code
    By lenny in forum New To Java
    Replies: 3
    Last Post: 07-25-2007, 07:59 PM

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •