Merge pull request #63203 from YuriSizov/a-gaping-hole-in-my-docs

Add more call-to-action notes when documentation is missing
godotengine · Nov 17, 2022 · 7d9923b · 7d9923b
2 parents b41ba33 + 270c810
commit 7d9923b
Show file tree

Hide file tree

Showing 3 changed files with 98 additions and 19 deletions.
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
@@ -723,15 +723,30 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
             f.write(make_type(child, state))
         f.write("\n\n")
 
+    has_description = False
+
     # Brief description
-    if class_def.brief_description is not None:
+    if class_def.brief_description is not None and class_def.brief_description.strip() != "":
+        has_description = True
+
         f.write(f"{format_text_block(class_def.brief_description.strip(), class_def, state)}\n\n")
 
     # Class description
     if class_def.description is not None and class_def.description.strip() != "":
+        has_description = True
+
         f.write(make_heading("Description", "-"))
         f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n")
 
+    if not has_description:
+        f.write(".. container:: contribute\n\n\t")
+        f.write(
+            translate(
+                "There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+            )
+            + "\n\n"
+        )
+
     # Online tutorials
     if len(class_def.tutorials) > 0:
         f.write(make_heading("Tutorials", "-"))
@@ -872,6 +887,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 if m.description is not None and m.description.strip() != "":
                     f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
+                else:
+                    f.write(".. container:: contribute\n\n\t")
+                    f.write(
+                        translate(
+                            "There is currently no description for this annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                        )
+                        + "\n\n"
+                    )
 
                 index += 1
 
@@ -904,6 +927,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
             if property_def.text is not None and property_def.text.strip() != "":
                 f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n")
+            else:
+                f.write(".. container:: contribute\n\n\t")
+                f.write(
+                    translate(
+                        "There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                    )
+                    + "\n\n"
+                )
 
             index += 1
 
@@ -925,6 +956,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 if m.description is not None and m.description.strip() != "":
                     f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
+                else:
+                    f.write(".. container:: contribute\n\n\t")
+                    f.write(
+                        translate(
+                            "There is currently no description for this constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                        )
+                        + "\n\n"
+                    )
 
                 index += 1
 
@@ -945,6 +984,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 if m.description is not None and m.description.strip() != "":
                     f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
+                else:
+                    f.write(".. container:: contribute\n\n\t")
+                    f.write(
+                        translate(
+                            "There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                        )
+                        + "\n\n"
+                    )
 
                 index += 1
 
@@ -967,6 +1014,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
                 if m.description is not None and m.description.strip() != "":
                     f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n")
+                else:
+                    f.write(".. container:: contribute\n\n\t")
+                    f.write(
+                        translate(
+                            "There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                        )
+                        + "\n\n"
+                    )
 
                 index += 1
 
@@ -992,6 +1047,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
 
             if theme_item_def.text is not None and theme_item_def.text.strip() != "":
                 f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n")
+            else:
+                f.write(".. container:: contribute\n\n\t")
+                f.write(
+                    translate(
+                        "There is currently no description for this theme property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!"
+                    )
+                    + "\n\n"
+                )
 
             index += 1
 

diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
@@ -446,7 +446,7 @@ Error EditorHelp::_goto_desc(const String &p_class, int p_vscr) {
 	return OK;
 }
 
-void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods, bool &r_method_descrpitons) {
+void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods) {
 	Ref<Font> font = get_theme_font(SNAME("doc_source"), SNAME("EditorFonts"));
 	class_desc->pop(); // title font size
 	class_desc->pop(); // title font
@@ -496,10 +496,6 @@ void EditorHelp::_update_method_list(const Vector<DocData::MethodDoc> p_methods,
 				class_desc->pop(); //cell
 			}
 
-			if (!m[i].description.strip_edges().is_empty() || m[i].errors_returned.size() > 0) {
-				r_method_descrpitons = true;
-			}
-
 			_add_method(m[i], true);
 		}
 
@@ -717,11 +713,15 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	bool has_description = false;
+
 	class_desc->add_newline();
 	class_desc->add_newline();
 
 	// Brief description
 	if (!cd.brief_description.strip_edges().is_empty()) {
+		has_description = true;
+
 		class_desc->push_color(text_color);
 		class_desc->push_font(doc_bold_font);
 		class_desc->push_indent(1);
@@ -736,6 +736,8 @@ void EditorHelp::_update_doc() {
 
 	// Class description
 	if (!cd.description.strip_edges().is_empty()) {
+		has_description = true;
+
 		section_line.push_back(Pair<String, int>(TTR("Description"), class_desc->get_paragraph_count() - 2));
 		description_line = class_desc->get_paragraph_count() - 2;
 		class_desc->push_color(title_color);
@@ -760,6 +762,22 @@ void EditorHelp::_update_doc() {
 		class_desc->add_newline();
 	}
 
+	if (!has_description) {
+		class_desc->add_image(get_theme_icon(SNAME("Error"), SNAME("EditorIcons")));
+		class_desc->add_text(" ");
+		class_desc->push_color(comment_color);
+
+		if (cd.is_script_doc) {
+			class_desc->append_text(TTR("There is currently no description for this class."));
+		} else {
+			class_desc->append_text(TTR("There is currently no description for this class. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
+		}
+
+		class_desc->pop();
+		class_desc->add_newline();
+		class_desc->add_newline();
+	}
+
 	// Online tutorials
 	if (cd.tutorials.size()) {
 		class_desc->push_color(title_color);
@@ -796,7 +814,6 @@ void EditorHelp::_update_doc() {
 
 	// Properties overview
 	HashSet<String> skip_methods;
-	bool property_descr = false;
 
 	bool has_properties = cd.properties.size() != 0;
 	if (cd.is_script_doc) {
@@ -874,7 +891,6 @@ void EditorHelp::_update_doc() {
 
 			if (describe) {
 				class_desc->pop();
-				property_descr = true;
 			}
 
 			class_desc->pop();
@@ -959,9 +975,6 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Methods overview
-	bool constructor_descriptions = false;
-	bool method_descriptions = false;
-	bool operator_descriptions = false;
 	bool sort_methods = EDITOR_GET("text_editor/help/sort_functions_alphabetically");
 
 	Vector<DocData::MethodDoc> methods;
@@ -989,19 +1002,20 @@ void EditorHelp::_update_doc() {
 		class_desc->push_font(doc_title_font);
 		class_desc->push_font_size(doc_title_font_size);
 		class_desc->add_text(TTR("Constructors"));
-		_update_method_list(cd.constructors, constructor_descriptions);
+		_update_method_list(cd.constructors);
 	}
 
 	if (!methods.is_empty()) {
 		if (sort_methods) {
 			methods.sort();
 		}
+
 		section_line.push_back(Pair<String, int>(TTR("Methods"), class_desc->get_paragraph_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
 		class_desc->push_font_size(doc_title_font_size);
 		class_desc->add_text(TTR("Methods"));
-		_update_method_list(methods, method_descriptions);
+		_update_method_list(methods);
 	}
 
 	if (!cd.operators.is_empty()) {
@@ -1014,7 +1028,7 @@ void EditorHelp::_update_doc() {
 		class_desc->push_font(doc_title_font);
 		class_desc->push_font_size(doc_title_font_size);
 		class_desc->add_text(TTR("Operators"));
-		_update_method_list(cd.operators, operator_descriptions);
+		_update_method_list(cd.operators);
 	}
 
 	// Theme properties
@@ -1507,7 +1521,7 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Property descriptions
-	if (property_descr) {
+	if (has_properties) {
 		section_line.push_back(Pair<String, int>(TTR("Property Descriptions"), class_desc->get_paragraph_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
@@ -1682,7 +1696,7 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Constructor descriptions
-	if (constructor_descriptions) {
+	if (!cd.constructors.is_empty()) {
 		section_line.push_back(Pair<String, int>(TTR("Constructor Descriptions"), class_desc->get_paragraph_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
@@ -1692,7 +1706,7 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Method descriptions
-	if (method_descriptions) {
+	if (!methods.is_empty()) {
 		section_line.push_back(Pair<String, int>(TTR("Method Descriptions"), class_desc->get_paragraph_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
@@ -1702,14 +1716,16 @@ void EditorHelp::_update_doc() {
 	}
 
 	// Operator descriptions
-	if (operator_descriptions) {
+	if (!cd.operators.is_empty()) {
 		section_line.push_back(Pair<String, int>(TTR("Operator Descriptions"), class_desc->get_paragraph_count() - 2));
 		class_desc->push_color(title_color);
 		class_desc->push_font(doc_title_font);
 		class_desc->push_font_size(doc_title_font_size);
 		class_desc->add_text(TTR("Operator Descriptions"));
 		_update_method_descriptions(cd, cd.operators, "operator");
 	}
+
+	// Free the scroll.
 	scroll_locked = false;
 }
 

diff --git a/editor/editor_help.h b/editor/editor_help.h
@@ -167,7 +167,7 @@ class EditorHelp : public VBoxContainer {
 
 	Error _goto_desc(const String &p_class, int p_vscr = -1);
 	//void _update_history_buttons();
-	void _update_method_list(const Vector<DocData::MethodDoc> p_methods, bool &r_method_descrpitons);
+	void _update_method_list(const Vector<DocData::MethodDoc> p_methods);
 	void _update_method_descriptions(const DocData::ClassDoc p_classdoc, const Vector<DocData::MethodDoc> p_methods, const String &p_method_type);
 	void _update_doc();