Documentation

Based on a previous post, I have 8 students (3 engineering, 5 programmers) here working on our school planetarium Empty Epsilon Project.
Based on past experience (full missions taking many many hours to write), our strategic plan is to have tasks for individuals or small task groups to:
1) Document Empty Epsilon/LUA functions with explanations of execution and variables and include operational examples in the form of good script uses of this function.
2) Make new useful functions for the Utils script library.

The main goal is to make mission scripting more powerful (and faster) for everyone instead of spending time figuring things out via reverse engineering someone else's script.

Daid had mentioned that the Script_reference.html is created at compile time and that he might want to somehow include any documentation here instead of GitHub WIKI or some other reference guide...

I'm not sure how this would be accomplished but... we have scripts and functions collecting on our Google doc and stand ready to follow your instructions to make this knowledge available to everyone in the form you instruct us to.

Comments

  • Well, the best place IMHO for the basic function documentation is with the function itself.
    So, at: https://github.com/daid/EmptyEpsilon/blob/master/src/spaceObjects/artifact.cpp#L9
    For example.
    Examples and everything can be put with that. Currently it doesn't allow any markup, but I can change that very quickly.

    My personal favorite example of decent documentation is with the SFML library:
    https://www.sfml-dev.org/documentation/2.4.2/index.php
    It has a tutorial, which is simply dedicated pages (like we have on the homepage) and the rest of the documentation is actually generated from the code.

    And then per object there is a short list of all function with 1 line descriptions, a detailed explination of the object with examples, and then detailed function descriptions. For example:
    https://www.sfml-dev.org/documentation/2.4.2/classsf_1_1Music.php


    Now can we do this for EE? Well, for the functions we can just show the first line in the "short list" and everything in the detailed description of the function. And the whole object examples we can put in the object description.
    With a bit of work, I can make the script_reference.html look a whole lot better if there is a lot of data in it, so don't worry about writting too much information for the current markup.



    Better util functions could be put directly in the utils.lua script:
    https://github.com/daid/EmptyEpsilon/blob/master/scripts/utils.lua
    Or, if that gets to big, into separate scripts.



    So, how do you get these changes there? Best way is with github pull requests.
    Basic workflow is:
    * You make a github fork of the EE code
    * You make a "clone" of this fork on your local computer
    * You make changes to this clone.
    * You commit and push these changes to your fork (the changes are now on github, but only in your fork)
    * You create a pull-request from your fork
    * I will review the changes and pull in the changes into the "master" codebase.
    * A new release will be build with these changes.
    There are better tutorials online that explain how to do this, and what tools you need.

    This is the standard open-source development workflow. And it's even close to the workflow we use at our office for all our development.
  • Thanks Daid,
    Your SFML examples are indeed impressive with easy to read formatting and examples.

    To repeat out loud what you are saying is that we will be inserting our proposed documentation into some file of the main project (via the fork,clone,pull request process)...
    We are getting up to speed on this GitHub workflow process in preparation.
    but.. We are unclear as to exactly what file and in what format or markup that will be usable/accepted by your compile process.
    If we had a template from you with formatting how you want it and 'in situ' of the correct project file. Most of the guess work would be gone and we could fork and start replicating that template for the other functions.

    Our goal is to have an easy to access, read, search resource to streamline the mission scripting process for anyone who wants to build, especially beginners.

    ------------Sample of what we have been writing:----------

    From Script_reference.html--------
    ----------------------------------
    PlayerSpaceship:addCustomButton(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback)
    -------------------

    Proposed Version ----------------
    ---------------------------------
    PlayerSpaceship
    ----
    :addCustomButton(ECrewPosition position, string name, string caption, ScriptSimpleCallback callback)

    DESCRIPTION:
    Run a function with a console button set at a crew console.

    PARAMETERS:
    #1) ECrewPosition position -> what console gets the button.
    "string"-> Relay, Helms, Weapons, Engineering (also shows on Engineering+), Single (Single Pilot)
    note: invalid-> Science, DamageControl, Tactical, Operations

    #2) string name -> Internal script object name of the button.
    Useful for removal of button via script. (See PlayerSpaceship:removeCustom(string name))
    "string"
    note: all buttons must have unique names.

    #3) string caption -> Button Label as seen in game in all caps.
    "string"

    #4) ScriptSimpleCallback callback -> The next lines are what the button does.
    function()
    Your script here
    end)

    EXAMPLE SCRIPT:
    Will display a button (WINGMEN ON ME) on the single pilot console to order CPU fighters to defend player.

    playerFighter = PlayerSpaceship():setFaction("Human Navy"):setTemplate("Atlantis"):setCallSign("Apollo"):setPosition(0, 0)

    cpuFighter1 = CpuShip():setFaction("Human Navy"):setTemplate("MT52 Hornet"):setScanned(true):setPosition(0, 1000)

    cpuFighter2 = CpuShip():setFaction("Human Navy"):setTemplate("MT52 Hornet"):setScanned(true):setPosition(1000, 1)

    cpuFighter3 = CpuShip():setFaction("Human Navy"):setTemplate("MT52 Hornet"):setScanned(true):setPosition(1000, 1000)

    playerFighter:addCustomButton("Single", "defendPlayerButton", "Wingmen ON ME", function()

    cpuFighter1:orderDefendTarget(Player)
    cpuFighter2:orderDefendTarget(Player)
    cpuFighter3:orderDefendTarget(Player)
    end)
Sign In or Register to comment.