-
-
Notifications
You must be signed in to change notification settings - Fork 3.2k
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.
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
Mention documentation comments in GDScript basics #10097
base: master
Are you sure you want to change the base?
Mention documentation comments in GDScript basics #10097
Conversation
Calinou
commented
Oct 16, 2024
- See tutorials/scripting/gdscript/gdscript_exports godot-docs-user-notes#143 (comment).
0974145
to
8b882b8
Compare
8b882b8
to
bef0e50
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems fine to merge as-is, but I have two possible suggestions to bring this more in line with the rest of the page.
- Add a code block with the most common examples.
- Shorten the paragraph and just link to the main page, as is done for
Exports
andHistory
.
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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.