Class Docs – register docs in #[godot_api(secondary)], simplify docs registration logic
#1355
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Yarwin
added
feature
|
API docs are being generated and will be shortly available at: https://godot-rust.github.io/docs/gdext/pr-1355 |
Yarwin
force-pushed
the
fix-docs-in-godot-api-secondary
branch
2 times, most recently
from
b37c2c8 to
4830461
Compare
Yarwin
changed the title
#[godot_api(secondary)], simplify registration logic#[godot_api(secondary)], simplify docs registration logic
Houtamelo
pushed a commit
to Houtamelo/dead_gds_have_rights
that referenced
this pull request
Oct 4, 2025
Bromeon
reviewed
Oct 6, 2025
Comment on lines
15
to
23
| /// You should not manually construct this struct, but rather use [`DocsPlugin::new()`]. | ||
| #[derive(Debug)] | ||
| pub struct DocsPlugin { | ||
| /// The name of the class to register docs for. | ||
| pub(crate) class_name: ClassId, | ||
|
|
||
| /// The actual item being registered. | ||
| pub item: DocsItem, | ||
| } |
There was a problem hiding this comment.
Question on comment and field visibility: why is one pub(crate)?
There was a problem hiding this comment.
leftover after copy-pasting ClassPlugin (and extracting proper constructors).
godot-core/src/docs.rs
Outdated
| pub enum DocsItem { | ||
| Struct(StructDocs), | ||
| InherentImpl(InherentImplDocs), | ||
| VirtualMethods(&'static str), |
There was a problem hiding this comment.
Would it make sense to add a TraitImpl(TraitImplDocs) already, for consistency with the other enum variants? Also because we'd have a named field 🤔
godot-macros/src/docs.rs
Outdated
| * Copyright (c) godot-rust; Bromeon and contributors. | ||
| * This Source Code Form is subject to the terms of the Mozilla Public | ||
| * License, v. 2.0. If a copy of the MPL was not distributed with this | ||
| * file, You can obtain one at https://mozilla.org/MPL/2.0/. |
There was a problem hiding this comment.
Please move this to docs/mod.rs, I try not to use the other module style 🧐
godot-macros/src/docs.rs
Outdated
| /// XML attribute, as BBCode: `deprecated="DEPRECATED"`. | ||
| /// Contains whole paragraph annotated with a `@deprecated` tag. | ||
| deprecated_attr: String, | ||
| #[cfg(not(all(feature = "register-docs", since_api = "4.3")))] |
There was a problem hiding this comment.
I do wonder if we can simplify those to just check register-docs, as we already verify (AFAIR?) the compatibility with api-* features?
Maybe in separate PR after this is merged, so there's not too many changes at once.
Yarwin
force-pushed
the
fix-docs-in-godot-api-secondary
branch
from
4830461 to
9d302af
Compare
Yarwin
force-pushed
the
fix-docs-in-godot-api-secondary
branch
5 times, most recently
from
e34b423 to
e1ed40d
Compare
- Bugfix: Handle docs in `#[godot_api(secondary)]` - Code tweaks: Separate docs modules to not pollute rest of the code with `#[cfg(all(feature = "register-docs", since_api = "4.3"))]`. Simplify registration logic. - Create separate PluginRegistry for Docs and Docs only.
Yarwin
force-pushed
the
fix-docs-in-godot-api-secondary
branch
from
e1ed40d to
e1b84ba
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What problem does this PR solve?
The obvious one – #1354, additionally I finally decided to address cfg leaking all over the codebase – i.e. handling docs-related cfg attr and features happens in docs module, not… everywhere else 😅.
I created another plugin registry for docs alone; initial logic by @Houtamelo directly edited plugin item with
InherentImplbut I don't see it being maintainable (i.e. it is error prone + will devolve into chaos + mixing these boundaries is bad idea in general).I'm not sure if additional registry is the best idea but I couldn't find anything better 🤷 and it is still gated behind
register-docsfeature.I'm marking it as a feature, despite being an oversight 🧐.
Doc bugfixes and improvements
#[godot_api(secondary)]#[cfg(all(feature = "register-docs", since_api = "4.3"))]. Simplify registration logic.