Summary: Lua interface reference documentation shipped with
                 Project: Freeciv
            Submitted by: jtn
            Submitted on: Tue 17 Jul 2012 09:54:16 PM BST
                Category: None
                Priority: 5 - Normal
                  Status: None
                 Privacy: Public
             Assigned to: None
        Originator Email: 
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: 



Currently, the primary documentation for our Lua scripting interface lives on
wikia <http://freeciv.wikia.com/wiki/Events_Reference_Manual>, miles away from
the code.

In general I'm uncomfortable with relying on external links for important
documentation rather than including it in the tarballs. In this case, there's
the more specific reasons that the documentation of what script hooks are
supposed to actually do is out of the way of C developers, so it's easy to
unintentionally change the behaviour, and it's easy to forget to update the
wiki when making changes; and it's a pain to keep them in sync even if you do

What I'd ideally like is some sort of Doxygen or Luadoc or similar style
documentation, where the descriptions live near the interface definitions
(ideally in *.pkg), and an up-to-date reference can be easily generated with
cross-references and what have you.

I haven't found a standard way of doing this for Lua interfaces to non-Lua
code (as opposed to pure Lua) such as tolua. I'll dump here a couple of
vaguely relevant links that have been sitting in my browser tabs for the past
few months: one <http://lua-users.org/lists/lua-l/2011-03/msg00537.html>, two

Whatever tool/scripts are used to generate the cross-reference from the source
code will probably become a prerequisite of "make dist", so that every tarball
ends up with an accurate Lua reference.
(If this is too onerous, we could of course check in generated documentation
to svn, but I'd rather not.)


Reply to this item at:


  Message sent via/by Gna!

Freeciv-dev mailing list

Reply via email to