[tracker] Tidy public internal interfaces

[ghost]

To facilitate macros and generated bindings, the bindings expose a considerable number of internal interfaces that are pub at the language level. This alone is not a problem. However, they currently float freely in the codebase, and have inconsistent #[doc(hidden)] attributes. There are also some items that are unnecessarily #[doc(hidden)] pub. This complicates maintenance and future improvements (support for multiple engine versions, for example).

As a general rule, all items that expose types from gdnative-sys will be considered internal starting 0.9 (#291). If there are no higher-level replacements for them, such wrappers should be created.

Following is a non-exhaustive listing of items that need attention. New instances may be added here as they are discovered.

Top-level items in gdnative-core

These are mostly used in macros, and will be moved to a module named private that is #[doc(hidden)] pub. There are two items without #[doc(hidden)], result_from_sys and report_init_error, that need special intervention:

• Deprecate result_from_sys in 0.8.1. It will be replaced with a from_sys method on GodotError. (Top-level hidden interface cleanup #360)
• report_init_error is not released yet. Move it to private directly in 0.8.1. (Top-level hidden interface cleanup #360)
• Make GODOT_API and GDNATIVE_LIBRARY_SYS fully private. (Top-level hidden interface cleanup #360)
• Remove top-level stubs in 0.9. (Remove deprecated items from the public interface #408)

Generated unsafe methods in bindings_methods.rs

These are only used in the generated inherent methods, and thus should simply be private.

• Make generated unsafe methods private. ([357]: making internal fns and structs private. #418)

this field in generated binding types

These should also just be private. Macros should use to_sys() instead.

• Make this fields private. (#357: Make this fields private. #405)

GodotObject and similar traits

The GodotObject trait is only meant to be implemented by the binding generator. However, there has been confused users trying to implement it (usually because they want downcasting). The trait should be "semi-sealed" with a supertrait in gdnative_code::private.

• "Semi-seal" GodotObject in 0.8.1 (Semi-seal the GodotObject trait. #368)
• "Semi-seal" free_on_drop::Free in 0.9 (Remove deprecated items from the public interface #408)
• "Semi-seal" free_on_drop::QueueFree in 0.9 (Remove deprecated items from the public interface #408)

Traits that are `#[doc(hidden)] but should be public and sealed

• access::Guard ([357] Sealing access::{Guard, WritePtr} #477)
• access::WritePtr ([357] Sealing access::{Guard, WritePtr} #477)

The Export trait and ExportInfo

It's not sure if Export should be sealed, since making custom types usable in properties is a reasonable use case. However, ExportInfo exposes sys::godot_property_hint as a public field, making it unsuitable to be public interface in future versions. The current plan is to deprecate the public fields in ExportInfo and make them private in 0.9.

• Add accessors and deprecate the public fields of ExportInfo in 0.8.1. (Deprecate public fields of ExportInfo #362)
• Make all fields of ExportInfo private in 0.9. (Remove deprecated items from the public interface #408)

init_handle field of ClassBuilder

• Make ClassBuilder::init_handle private. (#357: make init_handle private #404)

sys::godot_gdnative_terminate_options argument in godot_gdnative_init and gdnative_terminate callbacks

• Add high-level wrapper for init_options in 0.9.
• Add high-level wrapper for terminate_options in 0.9.

---

Opinions and items to add to the list are welcome!

[halzy]

Make generated unsafe methods private.

It appears that the remaining public functions are used across crates in the workspace. Were there specific functions you had in mind?

[ghost]

@halzy All the generated unsafe methods in bindings_methods.rs. They are #[doc(hidden)] so they won't show up in rustdoc, but they affect code completion apparently. Some changes might need to be made other than simply making them private.

[halzy]

@toasteater

Add high-level wrapper for init_options in 0.9.
Add high-level wrapper for terminate_options in 0.9.

Could you elaborate a bit more?

[ghost]

@halzy These types are used in the godot_gdnative_init and godot_gdnative_terminate macros as arguments to the callbacks. In 0.9 we want to have no gdnative-sys types in the public interface, so we should create high-level wrappers for them in gdnative-core to be used as arguments for those callbacks if that makes sense.

Otherwise, if there aren't any uses for them, we can also remove the arguments from the signatures of callbacks.