> > I would assume Inline POD is the way to go.
> > I am wondering if anyone has experiences counter to this.
>
> This is going to be an area of contention...
>
> I think POD has to go for this project. At least in its default form.
>
> We need something way more structured, that maintains API details to the
> extreme, like JavaDOC does, only we want something easier/better than
> JavaDOC.
Ah, a discussion I can contribute to, finally! ;-) I've given this a lot of
thought, having been disappointed in my own projects with the maintainability
of POD, and have gone to the trouble of creating a preliminary system for
maintaining API documentation using a combination of XML and perl comments.
If you want to see an example of what I've got, here it is:
The project is called ModInfo and is on SourceForge:
http://www.sf.net/projects/modinfo (it's young, still)
An example of the system's use can be found in my GUI builder project Guido
on SourceForge. One of the files in the application's CVS directory might be
a good example:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/guido/guido/lib/Guido/Applicat
ion.pm?rev=1.9&content-type=text/vnd.viewcvs-markup
(Whereever you see # MODINFO comments is where the documentation is being
placed)
You can also see the preliminary usage documentation here:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/modinfo/ModInfo/ModInfo/Tutori
al.pod?rev=1.1.1.1&content-type=text/vnd.viewcvs-markup
I designed the system to do two things, a) make it easy to update your API
documentation when you make changes to your code, and b) get the API info
into XML stored alongside the module itself so that you can convert it to
whatever you want whenever you want. Along the way, I ended up designing the
primary module for the system so that it could parse the XML into a set of
perl objects, which enables runtime inspection of API documentation from your
script (intellisense, anyone? ;-)
For those interested in such things, I somewhat copied the BeanInfo API from
the JavaBeans spec for the object structure. I deviated when I had to.
I also went so far as to work in something I call pseudo-typing. With
pseudo-typing, you specify in your API documentation whether you expect a
parameter or property to be an integer or string, for example, even though
Perl doesn't really care what you pass in or get out. This is solely to help
the developer understand your code, not to enforce any real datatyping. I
find that it's helping me understand my own Guido project much better, and
I've squashed several bugs just because I'm using the documentation now.
Oh, and there are two forms of the API documentation (so far), one is
embedded POD:
http://guido.sourceforge.net/doc/lib/Guido/Application.html
And one is a simple JavaDoc style API document:
http://guido.sourceforge.net/doc/interface/Guido/Application.html
The embedded POD is automatically updatable using the "INTERFACE" header as a
delimiter within the code. A script inserts the pod in the right place.
I'd love to hear ideas on how this could be improved or extended. One more
thing, an example of one of the .mfo (xml) files that is stored by the system
is attached for you to see.
jpt
<?xml version="1.0"?>
<modinfo>
<modules>
<module name="Guido::Application" version="0.03">
<functions>
<function name="splash_status"/>
<function name="trace_window" short_description="Displays a message to the trace window">
<param name="msg" data_type="Message" short_description="to write to trace window"/>
</function>
<function name="run" short_description="Used to start up Guido without having to call the new method."/>
<function name="eval_handler" short_description="Evaluates code passed into it">
<param name="eval_code" data_type="STRING" short_description="The code to evaluate"/>
</function>
<function name="find_in_path" short_description="Finds the provided file in the provided path">
<param name="file" data_type="STRING" short_description="File to find"/>
<paramarray name="path" short_description="Array of directories to search for the file"/>
</function>
</functions>
<methods>
<method name="TRACE" short_description="Tracing function for logging diagnostic messages">
<param name="msg" data_type="STRING" short_description="Message to send to trace"/>
<param name="trace_lvl" data_type="STRING" short_description="Level of tracing required to log msg"/>
</method>
<method name="enable_trace_window" short_description="Creates a TK window and starts logging TRACE messages to it."/>
<method name="disable_trace_window" short_description="Removes trace window from the display. Future TRACE messages go to STDOUT"/>
<method name="init_menu" short_description="Initializes Guido's menu"/>
<method name="init_toolbar" short_description="Initializes the toolbar for Guido"/>
<method name="init_macros" short_description="Initializes the currently registered macros"/>
<method name="init_plugins" short_description="Initializes the currently registered plugins"/>
<method name="reinit_plugin" short_description="Reinitializes a particular plugin, causing its display to refresh">
<paramhash name="params">
<key name="name" data_type="STRING" short_description="Name of plugin to reinitialize"/>
</paramhash>
</method>
<method name="reinit_app" short_description="Restarts the Guido IDE using the original command line parameters"/>
<method name="open_project" short_description="Opens a new project">
<paramhash name="params">
<key name="file_path" data_type="STRING" short_description="Path to the project file to be opened"/>
</paramhash>
<retval data_type="Guido::Project"/>
</method>
<method name="close_project" short_description="Closes a named project that is currently open in the IDE">
<paramhash name="params">
<key name="project_name" data_type="STRING" short_description="Name of project to close"/>
</paramhash>
<retval data_type="Guido::Project"/>
</method>
<method name="new_project" short_description="Creates a new project and returns it">
<paramhash name="params" short_description="This paramhash is passed directly to the Guido::Project new constructor"/>
<retval data_type="Guido::Project"/>
</method>
<method name="refresh" short_description="Reinits all plugins">
<retval/>
</method>
<method name="status" short_description="Updates the status bar at the bottom of the IDE">
<param name="status_msg" data_type="STRING" short_description="Message to be displayed (if empty, the status is reset to "Ready"/>
<retval data_type="INTEGER"/>
</method>
<method name="choose_project" short_description="Allows the choosing of a project using a file selection dialog box">
<retval/>
</method>
<method name="save_config" short_description="Saves the current in-memory configuration settings to disk">
<retval data_type="INTEGER"/>
</method>
<method name="edit_config" short_description="Displays the configuration editor dialog box">
<retval data_type="INTEGER"/>
</method>
<method name="place_menu" short_description="Allows a plugin to place a menu in the IDE's menu structure">
<param name="menu_name" data_type="STRING" short_description="Name of the menu in which to place the menu referenced by the menu_ref parameter"/>
<param name="submenu_name" data_type="STRING" short_description="Name to give the submenu"/>
<param name="menu_ref" data_type="Tk::Menu" short_description="Reference to the menu that is to be placed"/>
<retval data_type="INTEGER"/>
</method>
<method name="ERROR" short_description="Displays an error dialog box with the provided message">
<paramhash name="params">
<key name="text" data_type="STRING" short_description="Text to display in the dialog"/>
<key name="title" data_type="STRING" short_description="Title to give the dialog"/>
<key name="bitmap" data_type="STRING" short_description="Valid TK bitmap value to use when displaying the dialog"/>
<key name="buttons" data_type="ARRAYREF" short_description="Array reference to a list of strings to display as buttons"/>
<key name="default_button" data_type="STRING"/>
</paramhash>
<retval data_type="STRING"/>
</method>
</methods>
<constructors>
<constructor name="new" short_description="Constuctor that returns a reference to the main Guido Application object">
<param name="_hash" data_type="attribs"/>
<key name="trace_level" data_type="INTEGER" short_description="Level of tracing to perform"/>
<key name="trace_window" data_type="BOOLEAN" short_description="Send trace output to a scrollable window, instead of STDOUT"/>
</constructor>
</constructors>
<properties/>
<parent_classes>
<parent_class name="AutoLoader"/>
</parent_classes>
<dependencies>
<dependency type="module" target="strict"/>
<dependency type="module" target="vars"/>
<dependency type="module" target="Tk"/>
<dependency type="module" target="Tk::JPEG"/>
<dependency type="module" target="Tk"/>
<dependency type="module" target="Tk::JPEG"/>
<dependency type="module" target="Tk::Dialog"/>
<dependency type="module" target="FindBin"/>
<dependency type="module" target="XML::Simple"/>
<dependency type="module" target="Data::Dumper"/>
<dependency type="module" target="Guido::ConfigDialog"/>
<dependency type="module" target="Guido::Project"/>
<dependency type="module" target="Guido::RTData"/>
<dependency type="module" target="Guido::Tracer"/>
<dependency type="module" target="Guido::Plugin::Executor"/>
<dependency type="module" target="Guido::PluginLoader"/>
<dependency type="module" target="Guido::MacroLoader"/>
<dependency type="module" target="Tk::XMLMenu"/>
<dependency type="module" target="Tk::Toolbar"/>
<dependency type="module" target="Exporter"/>
<dependency type="module" target="AutoLoader"/>
<dependency type="module" target="constant"/>
<dependency type="module" target="Class::MethodMaker"/>
</dependencies>
</module>
</modules>
</modinfo>
