doc: Fix rendering and add some @see

Because the "within" was mixing properties and callback, 2 different
HTML templates were used in the same table. Mixing them didn't render
properly.

lib/gears/math/bezier.lua

@@ -20,6 +20,7 @@ local bezier = {}
 -- @treturn[1] number The value of `B(t)`.
 -- @treturn[2] nil `nil`, if c is empty.
 -- @staticfct gears.math.bezier.curve_evaluate_at
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_evaluate_at(c, t)
     local from = c
     local tmp = {nil, nil, nil, nil}
@@ -45,6 +46,7 @@ end
 -- @treturn {number,...} The table of control points for `B_left`.
 -- @treturn {number,...} The table of control points for `B_right`.
 -- @staticfct gears.math.bezier.curve_split_at
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_split_at(c, t)
     local coefs_left, coefs_right = {}, {}
     local from = c
@@ -73,6 +75,7 @@ end
 -- @treturn[1] {number,...} The table of control points of `B^(n)(t)`.
 -- @treturn[2] nil If n is less than 0.
 -- @staticfct gears.math.bezier.curve_derivative
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_derivative(c, n)
     n = n or 1
     if n < 0 then
@@ -121,6 +124,7 @@ end
 -- @treturn[2] nil nil, if n is less than 0.
 -- @treturn[3] number|nil The value of the zero parameter, if c is empty.
 -- @staticfct gears.math.bezier.curve_derivative_at
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_derivative_at(c, t, n, zero)
     local d = bezier.curve_derivative(c, n)
     if not d then
@@ -140,6 +144,7 @@ end
 -- @treturn[1] number The value of `B'(0)`.
 -- @treturn[2] number|nil The value of the zero parameter, if c is empty.
 -- @staticfct gears.math.bezier.curve_derivative_at_zero
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_derivative_at_zero(c, zero)
     local l = #c
     if l < 2 then
@@ -158,6 +163,7 @@ end
 -- @treturn[1] number The value of `B'(1)`.
 -- @treturn[2] number|nil The value of the zero parameter, if c is empty.
 -- @staticfct gears.math.bezier.curve_derivative_at_one
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_derivative_at_one(c, zero)
     local l = #c
     if l < 2 then
@@ -176,6 +182,7 @@ end
 -- @tparam {number,...} c The table of control points of the curve B.
 -- @treturn {number,...} The table of control points of the curve Q.
 -- @staticfct gears.math.bezier.curve_elevate_degree
+-- @see wibox.widget.graph.step_hook
 function bezier.curve_elevate_degree(c)
     local ret = {c[1]}
     local len = #c
@@ -213,6 +220,7 @@ end
 -- @treturn number c2
 -- @treturn number c3
 -- @staticfct gears.math.bezier.cubic_through_points
+-- @see wibox.widget.graph.step_hook
 function bezier.cubic_through_points(p0, p1, p2, p3)
     if not p1 then
         return p0, p0, p0, p0
@@ -246,6 +254,7 @@ end
 -- @treturn number c2
 -- @treturn number c3
 -- @staticfct gears.math.bezier.cubic_from_points_and_derivatives
+-- @see wibox.widget.graph.step_hook
 function bezier.cubic_from_points_and_derivatives(d0, p0, p3, d3)
     local c1 = p0 + d0/3
     local c2 = p3 - d3/3
@@ -271,6 +280,7 @@ end
 -- @treturn number c2
 -- @treturn number c3
 -- @staticfct gears.math.bezier.cubic_from_derivative_and_points_min_stretch
+-- @see wibox.widget.graph.step_hook
 function bezier.cubic_from_derivative_and_points_min_stretch(d0, p0, p3)
     local c1 = p0 + d0/3
     local c2 = (2*p0 - c1 + 3*p3) / 4
@@ -295,6 +305,7 @@ end
 -- @treturn number c2
 -- @treturn number c3
 -- @staticfct gears.math.bezier.cubic_from_derivative_and_points_min_strain
+-- @see wibox.widget.graph.step_hook
 function bezier.cubic_from_derivative_and_points_min_strain(d, p0, p3)
     local c1 = p0 + d/3
     local c2 = (c1 + p3) / 2
@@ -320,6 +331,7 @@ end
 -- @treturn number c2
 -- @treturn number c3
 -- @staticfct gears.math.bezier.cubic_from_derivative_and_points_min_jerk
+-- @see wibox.widget.graph.step_hook
 function bezier.cubic_from_derivative_and_points_min_jerk(d, p0, p3)
     local c1 = p0 + d/3
     local c2 = c1 + (p3 - p0) / 3

lib/wibox/widget/graph.lua

@@ -242,7 +242,7 @@ local graph = { mt = {} }
 -- @DOC_wibox_widget_graph_custom_draw_outline_EXAMPLE@
 --
 -- @property group_start
--- @within Advanced drawing
+-- @within Advanced drawing properties
 -- @tparam function|number|nil group_start
 -- @propemits true false
 
@@ -262,7 +262,7 @@ local graph = { mt = {} }
 -- @DOC_wibox_widget_graph_custom_draw_group_shift_EXAMPLE@
 --
 -- @callback group_start_callback
--- @within Advanced drawing
+-- @within Advanced drawing callbacks
 -- @tparam cairo.Context cr Cairo context
 -- @tparam number group_idx The index of the currently drawn data group
 -- @tparam @{draw_callback_options} options Additional info (@{draw_callback_options})
@@ -279,7 +279,7 @@ local graph = { mt = {} }
 -- @DOC_wibox_widget_graph_custom_draw_line_EXAMPLE@
 --
 -- @property group_finish
--- @within Advanced drawing
+-- @within Advanced drawing properties
 -- @tparam function|nil group_finish
 -- @propemits true false
 
@@ -293,7 +293,7 @@ local graph = { mt = {} }
 -- painting has taken place. This callback is supposed to do something about it.
 --
 -- @callback group_finish_callback
--- @within Advanced drawing
+-- @within Advanced drawing callbacks
 -- @tparam cairo.Context cr Cairo context
 -- @tparam number group_idx The index of the currently drawn data group
 -- @tparam @{draw_callback_options} options Additional info (@{draw_callback_options})
@@ -309,9 +309,10 @@ local graph = { mt = {} }
 -- @DOC_wibox_widget_graph_bezier_curve_EXAMPLE@
 --
 -- @property step_hook
--- @within Advanced drawing
+-- @within Advanced drawing properties
 -- @tparam function|nil step_hook
 -- @propemits true false
+-- @see gears.math
 
 --- User callback for drawing a value.
 --
@@ -342,7 +343,7 @@ local graph = { mt = {} }
 -- for graphs with values smaller than `baseline_value`.
 --
 -- @callback step_hook_callback
--- @within Advanced drawing
+-- @within Advanced drawing callbacks
 -- @tparam cairo.Context cr Cairo context
 -- @tparam number x The horizontal coordinate of the left edge of the bar.
 -- @tparam number value_y The vertical coordinate corresponding to the drawn value.
@@ -680,7 +681,7 @@ local function graph_draw_values(self, cr, width, height, drawn_values_num)
     -- all underscore-prefixed keys are reserved for future use by the widget.
     --
     -- @table draw_callback_options
-    -- @within Advanced drawing
+    -- @within Advanced drawing fields
     local options = {
         _graph = self, -- The graph widget itself.
         _width = width, -- The width it is being drawn with.