Skip to content

Latest commit

 

History

History
205 lines (161 loc) · 13.4 KB

README.md

File metadata and controls

205 lines (161 loc) · 13.4 KB
Raw

NeoDoc

NeoDoc is a simple documentation tool focused on language extensibility and simplicity, written from scratch in C#. It's one part of a duo project. NeoDoc is the backend, made to create different json files, used by the other frontend project, NeoVis.

TODO

  • Add multiline comment support (--[[ ... ]] or /* ... */)
  • Add exit codes for CI Jenkins
  • Add hints for wrong documentation style in common cases
  • Remove Check function of Datastructures (redundant)
  • If a Datastructure has an IgnoreParam, ignore the Datastructure. This can happen if not placing the IgnoreParam directly in the line before the Datastructure

Setup

How to add new languages?

  1. Duplicate Lua.cs.
  2. Rename the file into your new language (keep the file type .cs).
  3. Change the class name into the same as the file's name (for consistency).
  4. Modify the following function returns to support matching the new language:
Function Returns
GetName The name of the new language
GetFileExtension The file type of the new language
GetCommentStyleRegex RegEx of the a default file comment, -{2,} e.g. matches every line with two or more -
GetSingleCommentChar Character of a single line comment, e.g. - or /
GetCommentStartRegex RegEx of the default file comment block start, currently it's made to automatically register the @desc param, so you can start creating a description directly after using e.g. three dashes (---). Same as GetCommentStyleRegex
  1. Your language is now registered and can match the default Params :) But this tool still don't know who to assing the params to.

Datastructures

Datastructures are the wrappers that stores the Params. If no Datastructure is defined for your language, no Param can be stored and no documentation can be created.

Hot to add Datastructures to your language?

  1. Create a folder with the name of your registered language in the Datastructure folder.
  2. It's common to use a documentation tool to document functions, so we start with functions. Copy the Function Datastructure file of the Lua language and paste it into the created Datastructure folder of the new language.
  3. Rename the last ending of the namespace in this file into your new language.
  4. Modify the following function returns to support matching the new language:
Function Returns
GetName The identification name
GetRegex RegEx to match the current Datastructure in a line.
Check Check whether the current line matched this Datastructure [Depricated]
Process If the RegEx for this Datastructure matches, the Process function is run. Here, you can extract special data like arguments to keep them in your documentation.
GetData The exported data for the documentation
GetDatastructureName The name of the current Datastructure in the file, e.g. the line with the string CreateDocumentation(x, y, z) should return here CreateDocumentation
CheckDataStructureTransformation (optional) Used to check for a Datastructure transformation. Useful for subtype matching or similar things
GetFullJSONData (optional) The full JSON data of this Datastructure
IsGlobal (optional) Return true to move these Datastructure out of the current Wrapper, into the _global Wrapper

If you wanna get more data, take a look into this file.

Documentation parameter list

Params are used for any language, so you don't need to create a Param for any single language.

BaseParams

Most of all, they are derived from BaseParams (which doesn't get matched in the documentation) to avoid code redundancy. These are the BaseParams which already exists:

Param Utilization Arguments
Param This is the main BaseParam. Any new Param needs to be derived from it 0
MarkParam Used to mark a Datastructure (adding static data) 0
StateParam Used to assign one single data to a Datastructure 1
TextParam Used to add a text to the Datastructure 1
TypeTextParam Used to assign type and a desciption to a Datastructure 2
ParameterParam Used to assign a type, a name and a description to a Datastructure. This Param supports multiple types splitted by |. E.g. @param string|number x ... 3

Params

Currently, there already are these preregistered Params:

MarkParam
Param File Utilization
@2D 2DParam Functions that just run inside 2D hooks
@3D 3DParam Functions that just run inside 3D hooks
@deprecated DeprecatedParam Mark a Datastructure as deprecated
@hook HookParam Mark a Datastructure as a function, e.g. used in Lua
@ignore IgnoreParam Used to ignore the next line. To ignore a Datastructure, this needs to be placed directly the line before!
@important ImportantParam Mark a Datastructure as important
@internal InternalParam Mark a Datastructure as internal
@local LocalParam Mark a Datastructure as local. Currently just used by Lua, but can be used for private functions too. Datastructures marked as local are excluded from any documentation output (json file)!
@predicted PredictedParam Mark a Datastructure as predicted (used in Lua)
TextParam
Param File Utilization
@author AuthorParam Reference the creator of this function or module
@desc DescParam Automatically created if starting a comment block with e.g. --- in Lua. Used to add a desciption to the Datastructure
@function FunctionParam Used to create a function Datastructure in a comment, e.g. used in Lua. This needs to be the last Param, otherwise, the following Params will not be assigned to this new Datastructure
@note NoteParam Used to add a note to a Datastructure
@ref RefParam Used to reference a ressource. Derived from the @see Param
@see SeeParam Used to give a hint for the user to another information
@todo TodoParam Used to add information about what to do next for a Datastructure
@usage UsageParam Used to give a usage example for a Datastructure. It's common to add a code example here
@warning WarningParam Used to add a warning with a desciption to a Datastructure
StateParam
Param File Utilization
@name NameParam Used to override the name of the following Datastructure. Currently used by Lua for the CreateConVar Datastructure. Useful for dynamic names with a static structure
@realm RealmParam Used to set a realm of a Datastructure. In Lua, this can be client, server or shared (for both)
ParameterParam
Param File Utilization
@param ParamParam Used to add Parameter to a Datastructure, e.g. to register arguments of a function
TypeTextParam
Param File Utilization
@return ReturnParam Used to add the return types to a Datastructure, e.g. of a function

How is the data structured?

The data is structured in differnt layers. The order is the following:

  1. Wrapper (to add a custom Wrapper, use the custom @wrapper Param with one argument, the Wrapper's name)
  2. Section (to add a custom Section, use the custom @section Param with one argument, the Section's name)
  3. Datastructure
  4. Param

If there is no Wrapper or Section given, the default Wrapper or Section have the name "none". If you wanna add Datastructures into a Wrapper or Section and later switch back to the default Wrapper or Section, type @wrapper none or @section none. Globals (global Datastructures) are placed in the _globals Wrapper. They are not assigned to any Section!

How to add a custom Param?

  1. At first, you need to decide for a BaseParam. If there is no matching BaseParam, feel free to add your own one (It needs to be derived from the BaseParam Param and to be placed in the BaseParams folder) :)
  2. Then, give a look into the referenced Params above.
  3. Duplicate the Param's file
  4. Rename the file into your new Param's name
  5. Change the class' name to your new Param's name and adjust the BaseParam if you wanna use another one
  6. Modify the return of the GetName to match your new Param's name
  7. ...

Param Settings

Param Settings are made to define some default data or mark a Param e.g. as optional with opt. Values are assigned with =. Param Settings needs to be concatenated directly to the Param. Otherwise, it's handled as an argument!

These are the default Param Settings:

Param Setting Utilization Value Example
default Used to set a default value ✓ @param[default=true] boolean isUsed ...
opt Used to mark an Param as optional × @param[opt] Player target ...
optchain Used to mark an Param as optional chain × @param[optchain] Entity inflictor ...

Most of all, these Param Settings just makes sense in the ReturnParam or ParamParam.

Multiple Param Settings needs to be seperated from another with a ,, e.g. @param[default="Test", anotherSetting] string|number x ....

Anyways, you can use any string as a Param Setting you want. It's exported in the json entry settings.

Examples

---
-- This is a default description without a param
-- @param string x The test text
-- @return boolean Whether the test function was successful
function TestFunction1(x)
{
  -- ...
}

---
-- @author AuthorName
-- @wrapper TestWrapper

---
-- This function will be placed in the "TestWrapper" Wrapper, Section "none"
-- @realm client
function TestFunction2(x)
{
  -- ...
}

---
-- Another function that will be placed in the "TestWrapper" Wrapper
function TestFunction3(x)
{
  -- ...
}

-- @wrapper none

---
-- This function is placed in the "none" Wrapper
-- @function TestFunction4(x)
-- @param string x This will not be assigned to the previous function.

Output

There are 3 different outputs, which can be used to create a documentation frontend.

  1. The overview.json file, containing a complete list with the structure Wrapper -> Section -> Datastructure
  2. The search.json file. containing a shrinked list with the structure Wrapper -> Datastructure (so without section), commonly used for an improved searching
  3. The documentation of any Datastructure in the matching folder structure:
    • Wrapper name -> Datastructure name
    • or for global Datastructures: _globals as a Wrapper name -> Datastructure type name -> Datastructure name