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 17 Jul 2012 08:54:16 PM UTC  
 
Category: NonePriority: 5 - Normal
Status: NonePrivacy: Public
Assigned to: NoneOpen/Closed: Open
Planned Release: 

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

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

 

Tue 17 Jul 2012 08:54:16 PM UTC, 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):
   
   
Comment:
   

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.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item
    Show feedback again

    Back to the top


    Powered by Savane 3.1-cleanup