GodotNuts / GodotFirebase

Implementations of Firebase for Godot using GDScript
MIT License
532 stars 76 forks source link

Inline Class Documentation #120

Closed SIsilicon closed 3 years ago

SIsilicon commented 3 years ago

This pull requests aims to document the classes added by this project. That way, users can find references to the API from within the editor, just as how they would with builtin classes. image

Here's an example of how the documentation works.

## The first line is a brief description.
## Subsequent lines are part of the full description. All comments that start with "##" are considered document strings.
## Each class must be put before, or inline with certain keywords.
## In this case, this document block should be placed immediately above tool, extends, or class_name to be considered general class documentation.
## A document block may have annotations in each line. Each annotation has a particular meaning.
## 
## @tutorial https://link.to.tutorial
## @tutorial http://you.can.have/multiple
## @contribute https://link.to.where.you.contribute.documentation
## @meta-key value that metadata "key" will store (author, revision, etc...)
## 
## Use "@doc-ignore" if you don't want the script showing up in documentation.
## Also, the format used here is [i]special bbcode[/i]. That was just italized. [code]This is code.[/code]
extends Reference
class_name Example

## Nothing special
const CONSTANT = "r"

# If enumerator isn't named, its contents will be treated like individual constants.
# No, this isn't a doc string.
enum Enum{
    ENUM_A ## Description of ENUM_A
}

## @type var_type
## This is optional
##
## @default 0.0
## This needs to be defines if your variable has an initial value.
## 
## @enum SomeOtherClass.Enum
## If your variable holds an enum, define it here. If the enum were defines here, it could just be named directly without the dot.
##
## @setter set_var
## @getter get_var
## 
## This documentation will be for the variable defined below.
var foo := 0.0

var bar := 0 ## Documentation can be on the same line.

# variables and methods with "_" prepended are assumed to be private and ignored unless a doc string is defined before or alongside it.
var _private = null

## @args a, b, c, d
## Naming them is mandatory.
##
## @arg-types int, int, Spatial, Variant
## @arg-enums Enum
## @return int
## @return-enum Enum
## Use "@virtual" if the function is to be overwritten.
func something(a: Enum.ENUM_A, b: int, c: Spatial, d) -> int:
    return Enum.ENUM_A

## @arg-types float, int
## @arg-enums , Enum
signal some_signal(a, b)

Closes https://github.com/GodotNuts/GodotFirebase/issues/116.