C#: Documentation on supporting C# scripts in the Godot editor.

[magian1127]

    /// <summary>
    /// tip text
    /// </summary>
    [Export]
    string s1 = "AAAA";

resolve godotengine/godot-proposals#8269

[geekley]

Would it be possible to reuse this implementation for documentation of GDShader uniform fields? They are shown in the inspector, and it would be really useful for sharing shaders; e.g. on sites like https://godotshaders.com

[van800]

If this gets approved, it looks like worth setting
GenerateDocumentationFile in the Godot net sdk.

[mhilbrunner]

Removing the documentation label, as while this PR deals with documentation generation/display, this is more suited for the dotnet team to handle :)

[magian1127]

Remove the need for GenerateDocumentationFile=true.

[magian1127]

I have updated the PR based on the latest code.
Additionally, Delsin-Yu has implemented better XML documentation for BBCode rendering.
Since the changes are quite extensive, we encourage interested parties to test it out.

[Delsin-Yu]

For quick reference, the following C# code:

using Godot;
using System;
using System.Diagnostics;

/// <summary>
/// Comment for <see cref="NewScript"/>.
/// </summary>
public partial class NewScript : Node
{
    /// <summary>
    /// Comment for <see cref="_integerField"/>.
    /// </summary>
    /// <remarks>
    /// Additional remarks for <see cref="_integerField"/>.
    /// </remarks>
    [Export] private int _integerField = 42;
    
    /// <summary>
    /// Comment for <see cref="_stringField"/>.
    /// </summary>
    /// <exception cref="UnreachableException">This exception is never thrown.</exception>
    [Export] private string _stringField = "Hello, World!";
    
    /// <summary>
    /// Comment for <see cref="CustomSignalEventHandler"/>.
    /// </summary>
    /// <param name="value">The integer value emitted with the signal.</param>
    /// <param name="message">The string message emitted with the signal.</param>
    /// <returns>Nothing.</returns>
    /// <exception cref="ArgumentOutOfRangeException">Thrown when the value is out of range.</exception>
    [Signal]
    private delegate void CustomSignalEventHandler(int value, string message);
}

will be compiled to the following documentation and tooltips.

[Delsin-Yu]

Currently supported documentation blocks are:

• summary
• param
• returns
• exception
• remarks

Within each documentation block, the following cases are supported:

• <see cref="Type"/>
• <code>Code</code>
• <paramref name="message"/>
• <typeparamref name="T"/>
• <param name="value">Comment and supported cases</param>
• <typeparam name="T">Comment and supported cases</typeparam>

[geekley]

Question: does this implementation also support (currently or planned) disabling or overriding the tooltip if I want to have the XMLDoc different from the tooltip, via an attribute? (in this case it could even be BBCode if that's easier)
For example:

///<summary>Docs for both code and tooltip.</summary>
[Export] int health;

///<summary>Docs for code.</summary>
[Tooltip("""
Shows as [code]tooltip[/code].
""")]
[Export] int magic;

///<summary>Docs for code only.</summary>
[Tooltip("")] // no tooltip
[Export] int speed;

[Delsin-Yu]

No currently, but a dedicated [Tooltip] attribute sounds like a decent addition as a future PR.

[Delsin-Yu]

🤔 A second thought, should we try to interpret <inheritdoc/ >? I brought this up because when I'm adopting this to my personal project, I need to manually copy every comment I have from the interface members to their corresponding implementation type. In theory, a better UX should be:

[GlobalClass]
public partial class CharacterModel : Resource, ICharacter
{
    /// <inheritdoc cref="ICharacter.Name" />
    [Export] private string _characterName;
}

[geekley]

Very very minor, but it might be more prudent to render <remarks> literally as "Remarks:" instead of anything else, like "Note:", so it's exactly as written. For example, if someone happens to write <remarks>Note: blah blah.</remarks> they'd end up with a duplicate "Note: Note: blah blah.".

[PanzerKadaver]

Hi Godot Team,

Can we have an update on this one ? This kind of feature is much needed when your codebase start to reach a critical size. Especially when you start to transfer the backend logic of your game to a plugin.