Need documentation for map scripting

Issue #67 resolved
Carsten Fuchs created an issue

Documentation for map scripting is currently essentially missing.

Need at least one Wiki page that - provides a good introduction and overview to the topic, and - (another page that) has reference documentation about for all methods available for each entity.

Comments (6)

  1. Carsten Fuchs reporter

    Some related thoughts:

    - There doesn't seem to be an easy way to ''directly'' employ Doxygen for documenting our C++ implemented Lua methods. - It would still be worthwhile to have some (semi-)automatic processing available, even if only to make sure that things are complete. - Need similar functionality not only for the map entity hierarchy, but for the GUI windows hierarchy as well.

  2. Carsten Fuchs reporter

    (In [254]) = Motivation = We need (reference) documentation for our (Lua-) scripting APIs.

    Problem

    The C++ methods that implement the Lua methods are not amenable to documenting them with Doxygen comments, because - the C++ method signatures are all of the form int ClassName::MethodName(lua_State* LuaState) and - this would totally mix our C++ API documentation with the Lua API documentation.

    However, instead of writing and maintaining all scripting documentation manually, it would still be desirable to employ Doxygen, e.g. for completeness, correctness, automatic links, etc.

    Solution (Key Idea)

    Observe that ''some'' (in fact, the big majority) of our C++-implemented Lua classes are managed in `cf::TypeSys::TypeInfoManT` instances already, especially the big map entities and GUI windows hierarchies. (In fact, one of the main purposes of the Type System is to facilitate our binding of C++ class hierarchies to Lua scripts.)

    Given that, additional "meta" knowledge about the classes is already readily available in a well accessible form, especially base classes and methods lists!

    This revision adds code for using that meta information for writing template Doxygen input files ("fake headers") that documentation writers can copy, customize and complete to create the desired reference documentation. Future changes that require regenerating the so created template files can easily be merged by text compare tools like BeyondCompare.

    Our remaining C++-implemented Lua modules that are not covered by the Type System remain to be documented manually.

    References #67.

  3. Carsten Fuchs reporter

    (In [255]) Scripting documentation: - Continued the work begun in the previous revision (r254), fixed and improved the code. - Used this code to create initial hpp files in Doxygen/scripting/ for future customization. - Added related Doxyfile configuration file and mainpage.hpp.

    C++ API documentation: - Revised the Doxygen/Doxyfile file. - Added a mainpage.hpp here as well.

    References #67.

  4. Log in to comment