godotengine / godot

Godot Engine – Multi-platform 2D and 3D game engine
https://godotengine.org
MIT License
88.72k stars 20.12k forks source link

Doctool regression: multiline description formatting is broken #12798

Closed akien-mga closed 6 years ago

akien-mga commented 6 years ago

Operating system or device, Godot version, GPU Model and driver (if graphics related): Any OS, current master (2e89dd19)

Issue description: Doctool outputs a wrong formatting for multiline descriptions, likely a regression from a recent change (@LeeZH). Example:

diff --git a/doc/classes/AStar.xml b/doc/classes/AStar.xml
index 10ca3035f..1ff58bb57 100644
--- a/doc/classes/AStar.xml
+++ b/doc/classes/AStar.xml
@@ -5,7 +5,8 @@
    </brief_description>
    <description>
        A* (A star) is a computer algorithm that is widely used in pathfinding and graph traversal, the process of plotting an efficiently directed path between multiple points. It enjoys widespread use due to its performance and accuracy. Godot's A* implementation make use of vectors as points.
-       You must add points manually with [method AStar.add_point] and create segments manually with [method AStar.connect_points]. So you can test if there is a path between two points with the [method AStar.are_points_connected] function, get the list of existing ids in the found path with [method AStar.get_id_path], or the points list with [method AStar.get_point_path].
+
+You must add points manually with [method AStar.add_point] and create segments manually with [method AStar.connect_points]. So you can test if there is a path between two points with the [method AStar.are_points_connected] function, get the list of existing ids in the found path with [method AStar.get_id_path], or the points list with [method AStar.get_point_path].
    </description>
    <tutorials>
    </tutorials>
@@ -45,12 +46,18 @@
            </argument>
            <description>
                Adds a new point at the given position with the given identifier. The algorithm prefers points with lower [code]weight_scale[/code] to form a path. The [code]id[/code] must be 0 or larger, and the [code]weight_scale[/code] must be 1 or larger.
-               [codeblock]
-               var as = AStar.new()
-               
-               as.add_point(1, Vector3(1,0,0), 4) # Adds the point (1,0,0) with weight_scale=4 and id=1
-               [/codeblock]
-               If there already exists a point for the given id, its position and weight scale are updated to the given values.
+
+[codeblock]
+
+var as = AStar.new()
+
+
+
+as.add_point(1, Vector3(1,0,0), 4) # Adds the point (1,0,0) with weight_scale=4 and id=1
+
+[/codeblock]
+
+If there already exists a point for the given id, its position and weight scale are updated to the given values.
            </description>
        </method>
        <method name="are_points_connected" qualifiers="const">
@@ -82,15 +89,24 @@
            </argument>
            <description>
                Creates a segment between the given points.
-               [codeblock]
-               var as = AStar.new()
-               
-               as.add_point(1, Vector3(1,1,0))
-               as.add_point(2, Vector3(0,5,0))
-               
-               as.connect_points(1, 2, false) # If bidirectional=false it's only possible to go from point 1 to point 2
-                                              # and not from point 2 to point 1.
-               [/codeblock]
+
+[codeblock]
+
+var as = AStar.new()
+
+
+
+as.add_point(1, Vector3(1,1,0))
+
+as.add_point(2, Vector3(0,5,0))
+
+
+
+as.connect_points(1, 2, false) # If bidirectional=false it's only possible to go from point 1 to point 2
+
+                               # and not from point 2 to point 1.
+
+[/codeblock]
            </description>
        </method>
        <method name="disconnect_points">

Steps to reproduce: Run godot --doctool . in Godot's source and see the results.

akien-mga commented 6 years ago

Regression from #12025.