Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Mention documentation comments in GDScript basics #10097

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+7 −0
Open

Mention documentation comments in GDScript basics #10097

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions tutorials/scripting/gdscript/gdscript_basics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -572,6 +572,13 @@ considered a comment.
The list of highlighted keywords and their colors can be changed in the **Text
Editor > Theme > Comment Markers** section of the Editor Settings.

It is also possible to mark certain comments as
:ref:`documentation comments <doc_gdscript_documentation_comments>` by using
two hash symbols (``##``) instead of one (``#``). This only has an effect for
comments placed immediately *above* a documentable item (such as a member
variable), or at the top of a file. Dedicated formatting options are also
available. See :ref:`doc_gdscript_documentation_comments` for details.

Comment on lines +575 to +581
Copy link
Contributor

@tetrapod00 tetrapod00 Oct 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It is also possible to mark certain comments as
:ref:`documentation comments <doc_gdscript_documentation_comments>` by using
two hash symbols (``##``) instead of one (``#``). This only has an effect for
comments placed immediately *above* a documentable item (such as a member
variable), or at the top of a file. Dedicated formatting options are also
available. See :ref:`doc_gdscript_documentation_comments` for details.
Use two hash symbols (``##``) instead of one (``#``) to add a
:ref:`documentation comment <doc_gdscript_documentation_comments>`, which will
appear in the script documentation and in the inspector description of an
exported variable. Documentation comments must be placed directly *above* a
documentable item (such as a member variable), or at the top of a file.
Dedicated formatting options are also available.
See :ref:`doc_gdscript_documentation_comments` for details.
::
## This comment will appear in the script documentation.
var value
## This comment will appear in the inspector tooltip, and in the documentation.
@export var exported_value

(And also move this whole section to before the tip about special keywords, so the text flows better.)

I also changed the phrasing a bit to be more active and succinct.

Linking to the same page twice in a paragraph does seem a bit odd, but it's fine.

Comment on lines +575 to +581
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It is also possible to mark certain comments as
:ref:`documentation comments <doc_gdscript_documentation_comments>` by using
two hash symbols (``##``) instead of one (``#``). This only has an effect for
comments placed immediately *above* a documentable item (such as a member
variable), or at the top of a file. Dedicated formatting options are also
available. See :ref:`doc_gdscript_documentation_comments` for details.
It is also possible to mark certain comments as documentation
comments by using two hash symbols (``##``) instead of one (``#``).
See :ref:`doc_gdscript_documentation_comments` for details.

Alternately, following some other examples on this page, like History or Exports, only include a very minimal link to the page with the actual description, and don't link to the same page twice in a paragraph.

Code regions
~~~~~~~~~~~~

Expand Down