patchFreeciv - Patches: patch #3429, Lua interface reference...

Show feedback again

patch #3429: Lua interface reference documentation shipped with Freeciv

Submitted by:  Jacob Nevins <jtn>
Submitted on:  Tue Jul 17 20:54:16 2012  
Category: NonePriority: 5 - Normal
Status: NonePrivacy: Public
Assigned to: NoneOpen/Closed: Open
Planned Release: Contains string changes: None

Add a New Comment (Rich MarkupRich Markup):

You are not logged in

Please log in, so followups can be emailed to you.


Tue Jul 17 20:54:16 2012, original submission:

Currently, the primary documentation for our Lua scripting interface lives on wikia, 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, 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.)

Jacob Nevins <jtn>
Project Administrator


(Note: upload size limit is set to 1024 kB, after insertion of the required escape characters.)

Attach File(s):

No files currently attached


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -unavailable- added by jtn (Submitted the item)

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.


    Error: not logged in



    No Changes Have Been Made to This Item
    Show feedback again

    Back to the top

    Powered by Savane 3.1-cleanup