1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.
  2. Hey Guest, is it this your first time on the forums?

    Visit the Beginner's Box

    Introduce yourself, read some of the ins and outs of the community, access to useful links and information.

    Dismiss Notice
Cookies New to the forums?

Other Modding documentation project

Discussion in 'Modding [KAG]' started by Eluded, Mar 29, 2017.

Mods: jackitch, makmoud98, Skinney, Verrazano
  1. Eluded

    Eluded Haxor Official Server Admin

    Messages:
    132
    EDIT: Revised my post based on makmoud reminding me about the existing web documentation

    KAG's existing documentation at http://doc.kag2d.com/ should be improved.

    • Most classes are not documented. The web API lists CBlob, CMap, CPlayer, CRules, CSprite and ScriptData but this is only 5 of 62 available classes in the API (as listed in Manual/Objects.txt).
    • Most global functions are not documented. There is http://doc.kag2d.com/files/World/world-cpp.html#Globals but this is only 28 of 277 available global functions.
    • The other global functions, variables etc. are just given as lists of signatures. There are no descriptions or example usages for them (like http://doc.kag2d.com/index/Constants.html).
    • Hooks (e.g. onTick, onNewPlayerJoin) aren't listed or documented in the web docs (they are listed though in Manual/hooks.txt).
    Better documentation would be most useful for new modders but also useful for more experienced modders as a reference.
    What I would like to do is:

    • Improve the documentation to cover the majority of the API (including global variables, hooks etc.)
    • Add useful descriptions and example usages for each thing
    • Perhaps add some reference pages of how to do common things like creating a new blob, setting up a TCPR app, reading/writing data to config files, adding a new gamemode and so on.

    Please let me know if you think this is a good idea or if you would be interested to help.
     
    Last edited: Mar 29, 2017
    Eluded, Mar 29, 2017
    #1
    joshua12131415 and Osmal like this.
  2. makmoud98

    makmoud98 You are already DEAD Forum Moderator Staff Alumni Tester

    Messages:
    586
    makmoud98, Mar 29, 2017
    #2
  3. Geti

    Geti Please avoid PMing me (poke a mod instead) THD Team Administrator Global Moderator

    Messages:
    3,730
    We're currently using NaturalDocs - I'm personally not a huge fan, but it lets us work inline with the script definitions

    If you want to keep the same format, I'm happy to drop community contributed docs into the official system.

    Here's an example from the CBlob bindings showing how methods, properties, and global functions are documented, as well as a global function.

    Code:
        //class example
    /*
    Class: CBlob

    The main "game object" class, holds components and properties.

    Also provides mechanisms for sending and recieving commands,
    as well as for syncing properties from server to client and
    client to server.

    */

    //group example - this splits stuff up in the list
    /*
        Group: Script Related
     */

    //method example
    /*
        Function: CBlob.getCurrentScript
        Returns a handle to the <ScriptData> relating to the script that's currently running.

        Returns:
            ScriptData - this script's data.
    */
   
    //variable example
    /*
        Variable: CSprite.force_onrender
        Forcing OnRender to be called even if offscreen.
    */


    //global stuff
    /*
        Group: Globals

    */

    /*
        Function: server_CreateBlob()
            Creates a new blob in the world.

        Parameters:
            const string &in - blob config name
            int - team number
            Vec2f - position

        Return:
            CBlob@ - returns a reference to the newly created blob
    */
    Alternatively if you have a static site generator that you think would be more suitable I'm flexible, as I feel like natural docs isn't a great fit and I'd rather the docs get more use. Documenting hooks in naturaldocs doesn't seem to be possible either.

    I'm happy to contribute as appropriate as well; so far it's been thankless work though because there's not many folks modding and it seems like as soon as one class is well covered, people have trouble with another.
     
    Geti, Mar 30, 2017
    #3
  4. makmoud98

    makmoud98 You are already DEAD Forum Moderator Staff Alumni Tester

    Messages:
    586
    @Eluded i have an idea to code a script that will take the kag manual stuff like (objects.txt, functions.txt, etc) and then parse it into the website. then from there, we can write descriptions and more info on the parameters and stuff manually. this way whenever some new function is implemented/removed from kag, it will automatically be added to the docs
     
    makmoud98, Mar 30, 2017
    #4
    Osmal, Eluded and FunATuns like this.
  5. Fuzzle

    Fuzzle Grand Grumbler

    Messages:
    297
    GitHub wiki anyone? Commit it to kag-base.
     
    Fuzzle, Mar 30, 2017
    #5
    joshua12131415, Asu and Eluded like this.
  6. Eluded

    Eluded Haxor Official Server Admin

    Messages:
    132
    Yeah I agree this is a good idea. Also a similar script could look for example uses of each function in Base and automatically produce a short list to be included in the docs.
    --- Double Post Merged, Mar 31, 2017, Original Post Date: Mar 31, 2017 ---
    GitHub wiki sounds good to me. Markdown syntax is nice. The D3 API is documented with a GitHub wiki and that seems to work really well https://github.com/d3/d3/blob/master/API.md.
     
    Eluded, Mar 31, 2017
    #6
    joshua12131415 likes this.
  7. Asu

    Asu THD Team THD Team Forum Moderator

    Messages:
    1,580
    +1
    Writing a tool that dumps the manual as a markdown that can be modified (for description etc) would be nice to help with that (and to diff out on update to generate new ones).
     
    Asu, May 13, 2017
    #7
  8. Eluded

    Eluded Haxor Official Server Admin

    Messages:
    132
    It's exam season for me right now so I don't have much time for this. In a few weeks though I will be up for giving it some serious thought.
     
    Eluded, May 15, 2017
    #8
    Fuzzle likes this.
  9. Asu

    Asu THD Team THD Team Forum Moderator

    Messages:
    1,580
    Upping this thread. The KAG Base github repo doesn't seem to have the wiki functional (it just redirects to the root folder), I'd guess either because it has no first page or because it's disabled.
    An idea would be to create a new repo with the documentation as markdown, as a github website. The advantage over the wiki is that there are preset themes in and then you can modify the HTML and CSS as you want. This could be nice for some convenience tweaks (e.g. a more compact and practical layout than you'd get with plain markdown, like the current documentation has).

    Thoughts?
     
    Asu, Jun 2, 2017
    #9
    Fuzzle likes this.
  10. Fuzzle

    Fuzzle Grand Grumbler

    Messages:
    297
    Should be an official repo then.
     
    Fuzzle, Jun 2, 2017
    #10
  11. Asu

    Asu THD Team THD Team Forum Moderator

    Messages:
    1,580
    Yes, transhumandesign already shows up as an organization - it still could be made unofficially for testing and get merged to the organization later, if that's actually doable.
    --- Double Post Merged, Jul 2, 2017, Original Post Date: Jun 2, 2017 ---
    https://kagdocs.github.io/
     
    Asu, Jul 2, 2017
    #11
    Fuzzle likes this.
Mods: jackitch, makmoud98, Skinney, Verrazano