Godot: Documentation generator for gdscript

[CombustibleLemonade]

Have a javadoc-like documentation generator system for gdscript, such that documentation can be written in the comments (aka, contracts). This could also be made to generate documentation towards godots built-in class reference, and it could also allow for static typing (by specifying the type in the contract).

Example:

 # @method foo
 # @param bar extends Node
 # @return extends Reference
 func foo(bar):
     return bar

So what are your thoughts on this?

[neikeq]

Since GDScript has multi-line comments, wouldn't it be better to do it the Python Docstrings way?:

func foo(bar):
    """
    @method foo
    @param bar extends Node
    @return extends Reference
    """
    return bar

[CombustibleLemonade]

@neikeq Yes, that would be a good idea. I also see you wrote the documentation indented to the functions level, and I think that would be a good idea too, since then you could write documentation for the entire script from within the script itself.

[leonkrause]

Haven't used JavaDoc in a while, but Doxygen uses special comments (/// /**) to avoid ambiguity. So I suggest using something like ## with an extra character appended. Multiline comments already have 3 characters, so maybe something like """!

[Rocket-Buddha]

It would be great an output on markdown format.

[EIREXE]

I modified Doxygen to work with GDScript: https://github.com/PepperCarrotGame/doxygen

[ghostfreeman]

@EIREXE Have your changes to Doxygen been merged back into the project, and if not, do I need to build them with an existing Doxygen setup or is there another way to implement support? There hasn't been any real progress on this issue besides your changes, and outside of optionally abiding by PEP 257 (which I choose to do), Javadoc-style functionality seems to be a moot point for the community.

[EIREXE]

@ghostfreeman no, my changes replace python, so ti's a completely custom build, i was unable to add gdscript as an standalone language, which I would have liked to do.

[PrinceMerluza]

Would like this

[paulhocker]

I have been coding with the intention of finding or building a document generator. Here is an example of a Class I have created with docstrings inserted. I am interested in building something to do this, but I also do not want to re-invent the wheel. The Doxygen solution is nice, but follows PEP 257 which is too coupled for GDScript. Another option is to create a utility to read through the source and then build a interim file that can be fed to another engine like Doxygen or JavaDoc. Regardless, this is on my long list - for now at least my comments look nice.

#   
#   A Thing is Something that exists in the Game
#
#   @remarks
#   A Thing is Nothing but it is Everything. For that
#   reason, Everything in the Game must be a Thing.
#
#   @copyright
#   Copyright 2018, SpockerDotNet LLC
#

extends Node


const Uuid = preload("res://DoaCore/Uuid.gd")   


#   @type:uuid The Unique Identifier 
var id = "" setget , _get_id
#   @type:bool Is this Thing Active
var is_active = true
#   @type:bool Is this Thing Visible
var is_visible = true


#   @PUBLIC


#   @PRIVATE


func _get_id():
#
#   Getter for the Id for this Thing
#   
#   @returns
#   @uuid A Unique Identifier (UUID)    
#
    return id


#   @GODOT


func _init():
    Logger.trace("Thing:_init")
    id = Uuid.new()
    Logger.fine(id.uuid)

[toger5]

Would this documentation add a entry in godots builtun docs? Or just hover information?

[paulhocker]

I am talking about external documentation, like RTD. Although if I knew how to make mods to the editor I would like to have something like this. I do not think that there is ANY hover capability (except in debug mode) that I am aware of in the GDScript editor.

[paulhocker]

I have had some success using a Generic Documentation generator called Natural Docs.

https://www.naturaldocs.org/

It has a very simple and easy syntax, and implementing it for GDScript was pretty trivial. It even handled something slightly more complex like preventing a Private Function (one with an underscore) from producing output.

I am still experimenting with it to see if it can do things like document class inheritence, etc, but for now it seems to be a better solution that having to wait for something custom to be built in DoxyGen. It might also be good enough so that the main developers do not need to add anything custom to generate documentation.

I will report back here, and hopefully have a sample project for people to try.

Here is a sample of a Script file with comments:

"""
    Class: Thing
    A Thing is Something that exists in the Game

    Remarks:
    A Thing is Nothing but it is Everything. For that
    reason, Everything in the Game must be a Thing.

    See Also:
    <uuid>

    Copyright:
    Copyright 2018, SpockerDotNet LLC

"""

extends Reference


var UUID = doa_core.UUID


#   @type:uuid The Unique Identifier
var id = "" setget , _get_id
#   @type:bool Is this Thing Active
var is_active = true
#   @type:bool Is this Thing Visible
var is_visible = true


#   @PUBLIC


#   @PRIVATE


"""
    Private Function: _get_id
    Getter for the Id for this Thing

    Returns:
    A Unique Identifier (UUID)  
"""
func _get_id():
    return id.uuid

#   @GODOT


func _init():
    logger.fine("thing:_init")
    id = UUID.new()

[zak-grumbles]

Is there still any interest in this? I'd be interested in taking a swing at it if there's still need for it.

[paulhocker]

what are you thinking? the problem with the above solutions is that there is no way to properly identify and manage a class hierarchy. this is something I feel a lot of people would want. for me personally, i have just been doing things manually. of course, this does not scale very well.

[zak-grumbles]

I don't have a specific approach in mind yet. I guess it depends on what the desired functionality is.

• What does it actually generate? Markup, XML, etc?
• How should a user generate the docs? Does it happen on save, via a button in the editor?

[paulhocker]

I have wondered if it would be "easier" to look at making a custom plugin for Sphinx instead because GDScript is more Python based.

@zak-grumbles I am glad you have resurrected this thread. I had forgotten about it.

From my perspective I would "like" to see the remarks be worked into the code editor, so that for example, when you put a comment on a function it will show you that text when you hover over it in another part of your code

I am good building the docs outside of the editor, or having it part of the editor.

[Calinou]

The GDScript Docs Maker may be a good alternative to a built-in tool for now.

[paulhocker]

oh wow! how did i miss this one? I follow GDQuest too. I'll be checking this out. This might be enough, and I see it uses Hugo, which I am familiar with. Thanks for sharing this.

[akien-mga]

Feature and improvement proposals for the Godot Engine are now being discussed and reviewed in a dedicated Godot Improvement Proposals (GIP) (godotengine/godot-proposals) issue tracker. The GIP tracker has a detailed issue template designed so that proposals include all the relevant information to start a productive discussion and help the community assess the validity of the proposal for the engine.

The main (godotengine/godot) tracker is now solely dedicated to bug reports and Pull Requests, enabling contributors to have a better focus on bug fixing work. Therefore, we are now closing all older feature proposals on the main issue tracker.

If you are interested in this feature proposal, please open a new proposal on the GIP tracker following the given issue template (after checking that it doesn't exist already). Be sure to reference this closed issue if it includes any relevant discussion (which you are also encouraged to summarize in the new proposal). Thanks in advance!

---

Note: This is partially superseded by https://github.com/godotengine/godot-proposals/issues/177

@ThakeeNathees is working on a documentation system for GDScript as part of GSoC 2020.

https://github.com/GDQuest/gdscript-docs-maker is also available as an option in the meantime.