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.

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

Calinou
Copy link
Member

@Calinou Calinou commented Oct 16, 2024

@Calinou Calinou added enhancement topic:gdscript area:manual Issues and PRs related to the Manual/Tutorials section of the documentation cherrypick:4.3 labels Oct 16, 2024
@Calinou Calinou force-pushed the gdscript-basics-documentation-comments branch from 0974145 to 8b882b8 Compare October 16, 2024 15:53
@Calinou Calinou force-pushed the gdscript-basics-documentation-comments branch from 8b882b8 to bef0e50 Compare October 16, 2024 15:53
Copy link
Contributor

@tetrapod00 tetrapod00 left a 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 and History.

Comment on lines +575 to +581
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.

Copy link
Contributor

@tetrapod00 tetrapod00 Oct 16, 2024

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
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.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation cherrypick:4.3 enhancement topic:gdscript
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants