URL:
  <http://gna.org/patch/?3429>

                 Summary: Lua interface reference documentation shipped with
Freeciv
                 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: 

    _______________________________________________________

Details:

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
remember.

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
<http://lua-users.org/lists/lua-l/2011-03/msg00586.html>.

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:

  <http://gna.org/patch/?3429>

_______________________________________________
  Message sent via/by Gna!
  http://gna.org/


_______________________________________________
Freeciv-dev mailing list
Freeciv-dev@gna.org
https://mail.gna.org/listinfo/freeciv-dev

Reply via email to