Automatic documentation generation based on code

Registered by Sean Ryan

As part of the build process, there should be a "make docs" target added. This target will invoke some kind of utility ( most likely doxygen ) that will generate documentation from the source.

Blueprint information

Status:
Complete
Approver:
Erik Ogenvik
Priority:
Medium
Drafter:
Sean Ryan
Direction:
Approved
Assignee:
Erik Ogenvik
Definition:
Approved
Series goal:
None
Implementation:
Implemented
Milestone target:
None
Started by
Erik Ogenvik
Completed by
Erik Ogenvik

Related branches

Sprints

Whiteboard

This wouldn't be too hard to add. There's already an ember.dox file generated, so it's just to add a "docs" make target which will use that to create docs.

I've used the KDevelop doxygen wizard to get some docs built. They can be found here: http://amber.worldforge.org/ember/doc/html/
There's still a lot to be done with the documentation though. The doxygen file needs to be updated so that we get much more nicer html presentation. For example, the "namespace" tab only lists the topmost namespaces. And a lot of the classes have docs, but it doesn't show up in the class lists. I really like the way Ogre has it's html docs arranged, so we should aim for a similiar layout: http://www.ogre3d.org/docs/api/html/

One first step is to make sure that all class descriptions follow the doxygen standard and uses the /brief tag and similiar.
We should also add an introductory text in Ember.h.

Once we have it set up I plan on adding a cron job to amber which will rebuild the docs every night.

I've updated http://amber.worldforge.org/ember/doc/html/ with a better version. This one is easier to navigate within, but there's still some work to be done. We need to hide documentation for some internal classes of some of the subcomponents (such as internal OpCode classes). We also need to update the existing class documentation to use the doxygen tags such as @brief.
And we need to add documentation for a lot of classes and methods. The latter is something that's probably very hard to do for anyone but me though... /erik

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.