Merge #860

860: Update XML docs to Godot 3.4, output docs for 'custom-godot' r=Bromeon a=Bromeon



Co-authored-by: Jan Haller <[email protected]>

Author: bors[bot]

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018
+Copyright (c) 2017-2022 The godot-rust team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

bindings-generator/src/godot_api_json.rs

@@ -1,4 +1,5 @@
 use crate::godot_version;
+use std::fs;
 use std::path::PathBuf;
 use std::process::Command;
 
@@ -43,20 +44,50 @@ pub fn generate_json_if_needed() -> bool {
     exec(
         if has_generate_bug { 10 } else { 1 },
         Command::new(&godot_bin)
+            .arg("--no-window")
             .arg("--gdnative-generate-json-api")
             .arg("api.json"),
     );
 
+    // Best effort for generating the XML documentation
+    // Note: this documentation is not the same as shipped by official Godot releases, but it's the best we have.
+    exec_maybe(
+        1,
+        Command::new(&godot_bin)
+            .arg("--no-window")
+            .arg("--doctool")
+            .arg("."),
+    );
+
+    // Godot output structure           required structure
+    //
+    // +-- api.json
+    // +-- modules                      +-- api.json
+    // +-- doc                          +-- docs [*]
+    //     +-- classes [*]
+    //
+    let _ = fs::remove_dir_all("docs");
+    let _ = fs::rename("doc/classes", "docs");
+    let _ = fs::remove_dir("doc");
+    let _ = fs::remove_dir_all("modules");
+
     true
 }
 
 /// Executes a command and returns stdout. Panics on failure.
 fn exec(attempts: i32, command: &mut Command) -> String {
+    exec_maybe(attempts, command)
+        .unwrap_or_else(|| panic!("Could not execute Godot command (see above)."))
+}
+
+fn exec_maybe(attempts: i32, command: &mut Command) -> Option<String> {
     let command_line = format!("{:?}", command);
 
     for _attempt in 0..attempts {
         match command.output() {
-            Ok(output) => return String::from_utf8(output.stdout).expect("parse UTF8 string"),
+            Ok(output) => {
+                return Some(String::from_utf8(output.stdout).expect("parse UTF8 string"))
+            }
             Err(err) => {
                 eprintln!(
                     "Godot command failed:\n  command: {}\n  error: {}",
@@ -66,5 +97,5 @@ fn exec(attempts: i32, command: &mut Command) -> String {
         }
     }
 
-    panic!("Could not execute Godot command (see above).")
+    None
 }

gdnative-bindings/build.rs

@@ -33,14 +33,14 @@ fn main() {
     format_file_if_needed(&generated_rs);
     format_file_if_needed(&icalls_rs);
 
-    // build.rs will automatically be recompiled and run if it's dependencies are updated.
-    // Ignoring all but build.rs will keep from needless rebuilds.
-    // Manually rebuilding the crate will ignore this.
-    println!("cargo:rerun-if-changed=docs/");
+    // build.rs will automatically be recompiled and run if its dependencies are updated.
+    // Ignoring everything but build.rs will avoid needless rebuilds.
+    // Manually rebuilding the crate does not affect this.
     println!("cargo:rerun-if-changed=build.rs");
 
-    // Avoid endless recompiling, if this script generates api.json
+    // Avoid endless recompiling, if this script generates api.json and docs
     if !just_generated_api {
+        println!("cargo:rerun-if-changed=docs/");
         println!("cargo:rerun-if-changed=api.json");
     }
 }

gdnative-bindings/docs/@GlobalScope.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="@GlobalScope" version="3.3">
+<class name="@GlobalScope" version="3.4">
 	<brief_description>
 		Global scope constants and variables.
 	</brief_description>
@@ -883,7 +883,7 @@
 		<constant name="KEY_MASK_CTRL" value="268435456" enum="KeyModifierMask">
 			Ctrl key mask.
 		</constant>
-		<constant name="KEY_MASK_CMD" value="268435456" enum="KeyModifierMask">
+		<constant name="KEY_MASK_CMD" value="platform-dependent" enum="KeyModifierMask">
 			Command key mask. On macOS, this is equivalent to [constant KEY_MASK_META]. On other platforms, this is equivalent to [constant KEY_MASK_CTRL]. This mask should be preferred to [constant KEY_MASK_META] or [constant KEY_MASK_CTRL] for system shortcuts as it handles all platforms correctly.
 		</constant>
 		<constant name="KEY_MASK_KPAD" value="536870912" enum="KeyModifierMask">
@@ -1003,7 +1003,10 @@
 		<constant name="JOY_BUTTON_21" value="21" enum="JoystickList">
 			Gamepad button 21.
 		</constant>
-		<constant name="JOY_BUTTON_MAX" value="22" enum="JoystickList">
+		<constant name="JOY_BUTTON_22" value="22" enum="JoystickList">
+			Gamepad button 22.
+		</constant>
+		<constant name="JOY_BUTTON_MAX" value="23" enum="JoystickList">
 			Represents the maximum number of joystick buttons supported.
 		</constant>
 		<constant name="JOY_SONY_CIRCLE" value="1" enum="JoystickList">
@@ -1081,22 +1084,25 @@
 		<constant name="JOY_DPAD_RIGHT" value="15" enum="JoystickList">
 			Gamepad DPad right.
 		</constant>
-		<constant name="JOY_MISC1" value="16" enum="JoystickList">
+		<constant name="JOY_GUIDE" value="16" enum="JoystickList">
+			Gamepad SDL guide button.
+		</constant>
+		<constant name="JOY_MISC1" value="17" enum="JoystickList">
 			Gamepad SDL miscellaneous button.
 		</constant>
-		<constant name="JOY_PADDLE1" value="17" enum="JoystickList">
+		<constant name="JOY_PADDLE1" value="18" enum="JoystickList">
 			Gamepad SDL paddle 1 button.
 		</constant>
-		<constant name="JOY_PADDLE2" value="18" enum="JoystickList">
+		<constant name="JOY_PADDLE2" value="19" enum="JoystickList">
 			Gamepad SDL paddle 2 button.
 		</constant>
-		<constant name="JOY_PADDLE3" value="19" enum="JoystickList">
+		<constant name="JOY_PADDLE3" value="20" enum="JoystickList">
 			Gamepad SDL paddle 3 button.
 		</constant>
-		<constant name="JOY_PADDLE4" value="20" enum="JoystickList">
+		<constant name="JOY_PADDLE4" value="21" enum="JoystickList">
 			Gamepad SDL paddle 4 button.
 		</constant>
-		<constant name="JOY_TOUCHPAD" value="21" enum="JoystickList">
+		<constant name="JOY_TOUCHPAD" value="22" enum="JoystickList">
 			Gamepad SDL touchpad button.
 		</constant>
 		<constant name="JOY_L" value="4" enum="JoystickList">
@@ -1364,7 +1370,7 @@
 			Hints that an integer or float property should be within a range specified via the hint string [code]"min,max"[/code] or [code]"min,max,step"[/code]. The hint string can optionally include [code]"or_greater"[/code] and/or [code]"or_lesser"[/code] to allow manual input going respectively above the max or below the min values. Example: [code]"-360,360,1,or_greater,or_lesser"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_EXP_RANGE" value="2" enum="PropertyHint">
-			Hints that an integer or float property should be within an exponential range specified via the hint string [code]"min,max"[/code] or [code]"min,max,step"[/code]. The hint string can optionally include [code]"or_greater"[/code] and/or [code]"or_lesser"[/code] to allow manual input going respectively above the max or below the min values. Example: [code]"0.01,100,0.01,or_greater"[/code].
+			Hints that a float property should be within an exponential range specified via the hint string [code]"min,max"[/code] or [code]"min,max,step"[/code]. The hint string can optionally include [code]"or_greater"[/code] and/or [code]"or_lesser"[/code] to allow manual input going respectively above the max or below the min values. Example: [code]"0.01,100,0.01,or_greater"[/code].
 		</constant>
 		<constant name="PROPERTY_HINT_ENUM" value="3" enum="PropertyHint">
 			Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string such as [code]"Hello,Something,Else"[/code].