| [pde-dev] Autogenerating plugin documentation |
|
Hi everyone, My name is Anthony Cunningham and I am currently employed
writing plug-ins for eclipse, not open source plugs-ins unfortunately J. Recently we got a request for comprehensive documentation for
some plug-ins/products and I realized how much meta-information is contained in
the plugin.xml, ids, extensions, javadoc and class names. I assumed it
would be possible to auto generate the bulk of the documentation, both user and
reference, from this metadata. This ability could be improved by using class
names and dialog titles and messages. Working on the presumption that I rarely think of anything
that someone else hasn’t thought of at some stage I am asking this list
if this facility exists, or if someone is already doing it for personal
projects. If it doesn’t exist here are some ideas I’ve
had, if people know the best ways I could approach this, which methods/classes best
contain the metadata, or if people decide this is good functionality to add to
the Plug-In Development Environment please respond with your thoughts I guess the Holy Grail would be: In the requirements phase use cases and user stories could
auto generate basic Command and Wizard classes that could be fleshed out. I’m
not fully sure what commands are but I’m assuming in this case they are a
sort of abstract use case, and actions are the implementation of them. By
capturing all the use cases thus, a reference manual could list all the command
names and metadata. New project and file use cases could create basic wizards. In the PDE new plug-in project wizard the following messages
could be written into a user document: NewProjectWizard_MainPage_desc
= Create a new plug-in project By adding better prompts and messages to wizards this would flesh
out the user documentation. By using automation to launch wizards and code to capture
screenshots of the wizards and editors a lot of the screenshots common in
manuals could be automatically generated. The documentation could be created in Docbook and output to
multiple formats which include eclipse help. Auto generating EclipseMonkey/ GroovyMonkey scripts could give
users a live demo of the functionality of the plug-in. Its possible cheat sheets and help files with the
_javascript_:launchcommand links could also be generated. Document as a quality indicator: By creating the documentation this way, a cursory glance
would show weird class naming and inconsistent javadoc comments, by fixing
these in the code and the metadata both the code and the document quality would
improve. Technical/Architectural documentation would show up poor
packaging practices. Incremental document builder: The PDE could auto build documentation for plug-in being
developed similar to how it auto compiles classes. Example screenshot code: 1 Control c=((PartSite)window.getActivePage().getActivePart().getSite()).getPane().getControl(); 2 GC gc = new GC(c); 3 final Image image = new Image(Display.getCurrent(), c.getBounds()); 4 gc.copyArea(image, c.getBounds().x, c.getBounds().y); 5 gc.dispose(); These ideas are based on the DRY principle..Don’t
repeat yourself. http://en.wikipedia.org/wiki/Don't_repeat_yourself The requirements say the user should be able to create a new
DOMAIN_NAME project, the menu and wizard has “Create a new DOMAIN_NAME project”,
the user manual has a section Create a new DOMAIN_NAME project… Why should this information have to be entered multiple
times by the developer? I look forward to people’s thoughts and ideas, Anthony The information transmitted is intended
only for the person or entity to which it is addressed and may contain
confidential and/or privileged material. Any review, retransmission,
dissemination or other use of, or taking of any action in reliance upon, this
information by persons or entities other than the intended recipient is
prohibited. If you received this in error, please contact the sender and delete
the material from any computer. Duolog Technologies Limited, Company No.
316532. Registered Office: 1 The Pines, |