From d8b3efb0cdfe1ab1e67c5365746237877710bbd8 Mon Sep 17 00:00:00 2001
From: Astrale <jules180798@yahoo.fr>
Date: Tue, 7 Mar 2023 10:02:50 +0100
Subject: [PATCH] adds doc for log.rs adds doc tests to godot-macros

---
 godot-core/src/log.rs   | 10 ++++++
 godot-macros/src/lib.rs | 77 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/godot-core/src/log.rs b/godot-core/src/log.rs
index 23ff22fec..e2f619180 100644
--- a/godot-core/src/log.rs
+++ b/godot-core/src/log.rs
@@ -4,6 +4,9 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/// Pushes a warning message to Godot's built-in debugger and to the OS terminal.
+///
+/// _Godot equivalent: @GlobalScope.push_warning()_
 #[macro_export]
 macro_rules! godot_warn {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
@@ -21,6 +24,9 @@ macro_rules! godot_warn {
     };
 }
 
+/// Pushes an error message to Godot's built-in debugger and to the OS terminal.
+///
+/// _Godot equivalent: @GlobalScope.push_error()_
 #[macro_export]
 macro_rules! godot_error {
     // FIXME expr needs to be parenthesised, see usages
@@ -57,6 +63,9 @@ macro_rules! godot_script_error {
     };
 }
 
+/// Prints to the Godot console.
+///
+/// _Godot equivalent: @GlobalScope.print()_
 #[macro_export]
 macro_rules! godot_print {
     ($fmt:literal $(, $args:expr)* $(,)?) => {
@@ -75,6 +84,7 @@ pub use crate::{godot_error, godot_print, godot_script_error, godot_warn};
 use crate::builtin::{StringName, Variant};
 use crate::sys::{self, GodotFfi};
 
+/// Prints to the Godot console, used by the godot_print! macro.
 pub fn print(varargs: &[Variant]) {
     unsafe {
         let method_name = StringName::from("print");
diff --git a/godot-macros/src/lib.rs b/godot-macros/src/lib.rs
index 35eea339c..e2cd23785 100644
--- a/godot-macros/src/lib.rs
+++ b/godot-macros/src/lib.rs
@@ -4,6 +4,83 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+/// Extension API for Godot classes, used with `#[godot_api]`.
+///
+/// Helps with adding custom functionality:
+/// * `init` constructors
+/// * `to_string` method
+/// * Custom register methods (builder style)
+/// * All the lifecycle methods like `ready`, `process` etc.
+///
+/// These trait are special in that it needs to be used in combination with the `#[godot_api]`
+/// proc-macro attribute to ensure proper registration of its methods. All methods have
+/// default implementations, so you can select precisely which functionality you want to have.
+/// Those default implementations are never called however, the proc-macro detects what you implement.
+///
+/// Do not call any of these methods directly -- they are an interface to Godot. Functionality
+/// described here is available through other means (e.g. `init` via `Gd::new_default`).
+/// It is not enough to impl `GodotExt` to be registered in Godot, for this you should look at
+/// [ExtensionLibrary](crate::init::ExtensionLibrary).
+///
+/// If you wish to create a struct deriving GodotClass, you should impl the trait <Base>Virtual,
+/// for your desired Base (i.e. `RefCountedVirtual`, `NodeVirtual`).
+///
+/// # Examples
+///
+/// ## Example with `RefCounted` as a base
+///
+/// ```
+///# use godot::prelude::*;
+///
+/// #[derive(GodotClass)]
+/// struct MyRef;
+///
+/// #[godot_api]
+/// impl MyRef {
+///     #[func]
+///     pub fn hello_world(&mut self) {
+///         godot_print!("Hello World!")
+///     }
+/// }
+///
+/// #[godot_api]
+/// impl RefCountedVirtual for MyRef {
+///     fn init(_: Base<RefCounted>) -> Self {
+///         MyRef
+///     }
+/// }
+/// ```
+///
+/// The following example allows to use MyStruct in GDScript for instance by calling
+/// `MyStruct.new().hello_world()`.
+///
+///
+/// Note that you have to implement init otherwise you won't be able to call new or any
+/// other methods from GDScript.
+///
+/// ## Example with `Node` as a Base
+///
+/// ```
+///# use godot::prelude::*;
+///
+/// #[derive(GodotClass)]
+/// #[class(base=Node)]
+/// pub struct MyNode {
+///     #[base]
+///     base: Base<Node>,
+/// }
+///
+/// #[godot_api]
+/// impl NodeVirtual for MyNode {
+///     fn init(base: Base<Node>) -> Self {
+///         MyNode { base }
+///     }
+///     fn ready(&mut self) {
+///         godot_print!("Hello World!");
+///     }
+/// }
+/// ```
+///
 use crate::util::ident;
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;