11

I am working on documenting a new and expanded Lua API for the game Bitfighter (http://bitfighter.org). Our Lua object model is a subset of the C++ object model, and the methods exposed to Lua that I need to document are a subset of the methods available in C++. I want to document only the items relevant to Lua, and ignore the rest.

For example, the object BfObject is the root of all the Lua objects, but is itself in the middle of the C++ object tree. BfObject has about 40 C++ methods, of which about 10 are relevant to Lua scripters. I wish to have our documentation show BfObject as the root object, and show only those 10 relevant methods. We would also need to show its children objects in a way that made the inheritance of methods clear.

For the moment we can assume that all the code is written in C++.

One idea would be to somehow mark the objects we want to document in a way that a system such as doxygen would know what to look at and ignore the rest. Another would be to preprocess the C++ code in such a way as to delete all the non-relevant bits, and document what remains with something like doxygen. (I actually got pretty far with this approach using luadoc, but could not find a way to make luadoc show object hierarchy.)

One thing that might prove helpful is that every Lua object class is registered in a consistent manner, along with its parent class.

There are a growing number of games out there that use Lua for scripting, and many of them have decent documentation. Does anyone have a good suggestion on how to produce it?

PS To clarify, I'm happy to use any tool that will do the job -- doxygen and luadoc are just examples that I am somewhat familiar with.

Watusimoto
  • 1,773
  • 1
  • 23
  • 38

3 Answers3

2

I have found a solution, which, while not ideal, works pretty well. I cobbled together a Perl script which rips through all the Bitfighter source code and produces a second set of "fake" source that contains only the elements I want. I can then run this secondary source through Doxygen and get a result that is 95% of what I'm looking for.

I'm declaring victory.

One advantage of this approach is that I can document the code in a "natural" way, and don't need to worry about marking what's in and what's out. The script is smart enough to figure it out from the code structure.

If anyone is interested, the Perl script is available in the Bitfighter source archive at https://code.google.com/p/bitfighter/source/browse/luadoc.pl. It is only about 80% complete, and is missing a few very important items (such as properly displaying function args), but the structure is there, and I am satisfied the process will work. The script will improve with time.

The (very preliminary) results of the process can be seen at http://bitfighter.org/luadocs/index.html. The templates have hardly been modified, so it has a very "stock" look, but it shows that things more-or-less work.

Since some commenters have suggested that it is impossible to generate good documentation with Doxygen, I should note that almost none of our inline docs have been added yet. To get a sense of what they will look like, see the Teleporter class. It's not super good, but I think it does refute the notion that Doxygen always produces useless docs.

My major regret at this point is that my solution is really a one-off and does not address what I think is a growing need in the community. Perhaps at some point we'll standardize on a way of merging C++ and Lua and the task of creating a generalized documentation tool will be more manageable.

PS You can see what the markup in the original source files looks like... see https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp, and search for @luaclass

Watusimoto
  • 1,773
  • 1
  • 23
  • 38
1

Exclude either by namespace (could be class as well) of your C++ code, but not the lua code 

EXCLUDE_SYMBOLS = myhier_cpp::*

in the doxygen config file or cherry pick what to exclude by using

/// @cond
class aaa {
  ...
  ...
}

/// @endcond

in your c++ code.

I personally think that separating by namespace is better since it reflects the separation in code + documentation, which leads to a namespace based scheme for separation of pure c++ from lua bindings.

Separating via exclusion is probably the most targeted approach but that would involve an extra tool to parse the code, mark up relevant lua parts and add the exclusion to the code. (Additionally you could also render special info like graphs separately with this markup and add them via an Image to your documentation, at least that's easy to do with Doxygen.). Since there has to be some kind of indication of lua code, the markup is probably not too difficult to derive.

count0
  • 2,537
  • 2
  • 22
  • 30
  • It's quite impossible for Doxygen to produce good documentation. The only thing it can do is list methods. – Puppy Sep 12 '12 at 13:41
  • DeadMG: Depends on what you're doing with Doxygen. The Qt project uses a customized version of Doxygen (qtdoc), and produces one of the best API documentations I've ever seen. – Stefan Majewsky Sep 12 '12 at 14:47
  • @StefanMajewsky: He didn't say "Qt's *modified* Doxygen cannot produce good documentation." Doxygen does processing well, but the formatting of the documentation it produces leaves something to be desired. – Nicol Bolas Sep 12 '12 at 15:12
  • Formatting is done via html/css, which should be more than enough, plus there are bunch of templates available online. Doxygen produces callgraphs, UML class diagrams of your hierarchies, allows custom document structure as well as custom embedding of graphics and other content. – count0 Sep 12 '12 at 15:23
  • One problem with this approach is it seems that the parent classes of BfObject are still referenced, even if they are not included in the list of stuff to document. I will continue to experiment, but I think this will not produce the results I'm looking for. – Watusimoto Sep 12 '12 at 20:01
  • You can exclude by class as well, if you did so far by namespace. – count0 Sep 13 '12 at 18:44
0

Another solution is to use LDoc. It also allows you to write C++ comments, which will be parsed by LDoc and included into the documentation.

An advantage is that you can just the same tool to document your lua code as well. A drawback is that the project seems to be unmaintained. It may also not be possible to document complex object hierarchies, like the questioner mentioned.

I forked it myself for some small adjustments regarding c++. Have a look here.

flyingdutchman
  • 1,197
  • 11
  • 17