Update in-source documentation

Include/RmlUi/Core/CompiledFilterShader.h

@@ -37,7 +37,9 @@ namespace Rml {
 class RenderManager;
 
 /**
-    A compiled filter to be applied during layer pop in its render manager. A unique resource constructed through the render manager.
+    A compiled filter to be applied when compositing layers in the render manager.
+
+    Represents a unique render resource constructed through the render manager.
  */
 class RMLUICORE_API CompiledFilter final : public UniqueRenderResource<CompiledFilter, CompiledFilterHandle, CompiledFilterHandle(0)> {
 public:
@@ -53,7 +55,9 @@ private:
 };
 
 /**
-    A compiled shader to be used when rendering geometry. A unique resource constructed through the render manager.
+    A compiled shader to be used when rendering geometry.
+
+    Represents a unique render resource constructed through the render manager.
  */
 class RMLUICORE_API CompiledShader final : public UniqueRenderResource<CompiledShader, CompiledShaderHandle, CompiledShaderHandle(0)> {
 public:

Include/RmlUi/Core/Decorator.h

@@ -59,7 +59,7 @@ public:
 	/// Called on a decorator to generate any required per-element data for a newly decorated element.
 	/// @param[in] element The newly decorated element.
 	/// @param[in] paint_area Determines the element's area to be painted by the decorator.
-	/// @return A handle to a decorator-defined data handle, or nullptr if none is needed for the element.
+	/// @return A handle to a decorator-defined data handle, or zero if no data is needed for the element.
 	virtual DecoratorDataHandle GenerateElementData(Element* element, BoxArea paint_area) const = 0;
 	/// Called to release element data generated by this decorator.
 	/// @param[in] element_data The element data handle to release.
@@ -83,7 +83,7 @@ protected:
 	int GetNumTextures() const;
 	/// Returns one of the decorator's previously loaded textures.
 	/// @param[in] index The index of the desired texture.
-	/// @return The texture at the appropriate index, or nullptr if the index was invalid.
+	/// @return The texture at the appropriate index, or default-inititalized if the index was invalid.
 	Texture GetTexture(int index = 0) const;
 
 private:

Include/RmlUi/Core/EffectSpecification.h

@@ -59,8 +59,8 @@ protected:
 	/// Registers a shorthand property definition. Specify a shorthand name of 'decorator' or 'filter' to parse
 	/// anonymous decorators or filters, respectively.
 	/// @param[in] shorthand_name The name to register the new shorthand property under.
-	/// @param[in] properties A comma-separated list of the properties this definition is shorthand for. The order in
-	/// which they are specified here is the order in which the values will be processed.
+	/// @param[in] property_names A comma-separated list of the properties this definition is a shorthand for. The order
+	/// in which they are specified here is the order in which the values will be processed.
 	/// @param[in] type The type of shorthand to declare.
 	/// @return An ID for the new shorthand, or 'Invalid' if the shorthand declaration is invalid.
 	ShorthandId RegisterShorthand(const String& shorthand_name, const String& property_names, ShorthandType type);

Include/RmlUi/Core/Filter.h

@@ -47,15 +47,15 @@ public:
 	Filter();
 	virtual ~Filter();
 
-	/// Called on a decorator to generate any required per-element data for a newly decorated element.
-	/// @param[in] element The newly decorated element.
-	/// @return A handle to a decorator-defined data handle, or nullptr if none is needed for the element.
+	/// Called to compile the filter for a given element.
+	/// @param[in] element The element the filter will be applied to.
+	/// @return A compiled filter constructed through the render manager, or a default-constructed one to indicate an error.
 	virtual CompiledFilter CompileFilter(Element* element) const = 0;
 
-	/// Allows extending the area being affected by this filter beyond the border box of the element.
+	/// Called to allow extending the area being affected by this filter beyond the border box of the element.
 	/// @param[in] element The element the filter is being rendered on.
 	/// @param[in,out] overflow The ink overflow rectangle determining the clipping region to be applied when filtering the current element.
-	/// @note Modifying the ink overflow rectangle affects rendering of all filter decorators active on the current element.
+	/// @note Modifying the ink overflow rectangle affects rendering of all filters active on the current element.
 	/// @note Only affects the 'filter' property, not 'backdrop-filter'.
 	virtual void ExtendInkOverflow(Element* element, Rectanglef& overflow) const;
 };

Include/RmlUi/Core/FontEffectInstancer.h

@@ -56,7 +56,6 @@ public:
 	/// Instances a font effect given the property tag and attributes from the RCSS file.
 	/// @param[in] name The type of font effect desired. For example, "font-effect: outline(1px black);" is declared as type "outline".
 	/// @param[in] properties All RCSS properties associated with the font effect.
-	/// @param[in] interface An interface for querying the active style sheet.
 	/// @return A shared_ptr to the font-effect if it was instanced successfully.
 	virtual SharedPtr<FontEffect> InstanceFontEffect(const String& name, const PropertyDictionary& properties) = 0;
 
@@ -72,10 +71,10 @@ protected:
 	PropertyDefinition& RegisterProperty(const String& property_name, const String& default_value, bool affects_generation = true);
 	/// Registers a shorthand property definition.
 	/// @param[in] shorthand_name The name to register the new shorthand property under.
-	/// @param[in] properties A comma-separated list of the properties this definition is shorthand for. The order in which they are specified here is
-	/// the order in which the values will be processed.
+	/// @param[in] property_names A comma-separated list of the properties this definition is shorthand for. The order
+	/// in which they are specified here is the order in which the values will be processed.
 	/// @param[in] type The type of shorthand to declare.
-	/// @param True if all the property names exist, false otherwise.
+	/// @return An ID for the new shorthand, or 'Invalid' if the shorthand declaration is invalid.
 	ShorthandId RegisterShorthand(const String& shorthand_name, const String& property_names, ShorthandType type);
 
 private:

Include/RmlUi/Core/MeshUtilities.h

@@ -44,34 +44,30 @@ struct Mesh;
 class RMLUICORE_API MeshUtilities {
 public:
 	/// Generates a quad from a position, size and colour.
-	/// @param[out] vertices An array of at least four vertices that the generated vertex data will be written into.
-	/// @param[out] indices An array of at least six indices that the generated index data will be written into.
+	/// @param[out] mesh A mesh to append the generated vertices and indices into.
 	/// @param[in] origin The origin of the quad to generate.
 	/// @param[in] dimensions The dimensions of the quad to generate.
 	/// @param[in] colour The colour to be assigned to each of the quad's vertices.
-	/// @param[in] index_offset The offset to be added to the generated indices; this should be the number of vertices already in the array.
 	static void GenerateQuad(Mesh& mesh, Vector2f origin, Vector2f dimensions, ColourbPremultiplied colour);
 	/// Generates a quad from a position, size, colour and texture coordinates.
-	/// @param[out] vertices An array of at least four vertices that the generated vertex data will be written into.
-	/// @param[out] indices An array of at least six indices that the generated index data will be written into.
+	/// @param[out] mesh A mesh to append the generated vertices and indices into.
 	/// @param[in] origin The origin of the quad to generate.
 	/// @param[in] dimensions The dimensions of the quad to generate.
 	/// @param[in] colour The colour to be assigned to each of the quad's vertices.
 	/// @param[in] top_left_texcoord The texture coordinates at the top-left of the quad.
 	/// @param[in] bottom_right_texcoord The texture coordinates at the bottom-right of the quad.
-	/// @param[in] index_offset The offset to be added to the generated indices; this should be the number of vertices already in the array.
 	static void GenerateQuad(Mesh& mesh, Vector2f origin, Vector2f dimensions, ColourbPremultiplied colour, Vector2f top_left_texcoord,
 		Vector2f bottom_right_texcoord);
 
 	/// Generates the geometry required to render a line.
-	/// @param[out] geometry The geometry to append the newly created geometry into.
+	/// @param[out] mesh A mesh to append the generated vertices and indices into.
 	/// @param[in] position The top-left position the line.
 	/// @param[in] position The size of the line.
 	/// @param[in] color The color to draw the line in.
 	static void GenerateLine(Mesh& mesh, Vector2f position, Vector2f size, ColourbPremultiplied color);
 
 	/// Generates the geometry for an element's background and border, with support for the border-radius property.
-	/// @param[out] geometry The geometry to append the newly created vertices and indices into.
+	/// @param[out] mesh A mesh to append the generated vertices and indices into.
 	/// @param[in] box The box which determines the background and border geometry.
 	/// @param[in] offset Offset the position of the generated vertices.
 	/// @param[in] border_radius The border radius in pixel units in the following order: top-left, top-right, bottom-right, bottom-left.
@@ -82,7 +78,7 @@ public:
 		const ColourbPremultiplied border_colours[4]);
 
 	/// Generates the background geometry for an element's area, with support for border-radius.
-	/// @param[out] geometry The geometry to append the newly created vertices and indices into.
+	/// @param[out] mesh A mesh to append the generated vertices and indices into.
 	/// @param[in] box The box which determines the background geometry.
 	/// @param[in] offset Offset the position of the generated vertices.
 	/// @param[in] border_radius The border radius in pixel units in the following order: top-left, top-right, bottom-right, bottom-left.

Include/RmlUi/Core/PropertySpecification.h

@@ -94,15 +94,15 @@ public:
 
 	/// Registers a shorthand property definition.
 	/// @param[in] shorthand_name The name to register the new shorthand property under.
-	/// @param[in] properties A comma-separated list of the properties this definition is shorthand for. The order in which they are specified here is
-	/// the order in which the values will be processed.
+	/// @param[in] property_names A comma-separated list of the properties this definition is shorthand for. The order
+	/// in which they are specified here is the order in which the values will be processed.
 	/// @param[in] type The type of shorthand to declare.
 	/// @param[in] id If 'Invalid' then automatically assigns a new id, otherwise assigns the given id.
 	/// @return An ID for the new shorthand, or 'Invalid' if the shorthand declaration is invalid.
 	ShorthandId RegisterShorthand(const String& shorthand_name, const String& property_names, ShorthandType type,
 		ShorthandId id = ShorthandId::Invalid);
 	/// Returns a shorthand definition.
-	/// @param[in] shorthand_name The name of the desired shorthand.
+	/// @param[in] id The id of the desired shorthand.
 	/// @return The appropriate shorthand definition if it could be found, nullptr otherwise.
 	const ShorthandDefinition* GetShorthand(ShorthandId id) const;
 	const ShorthandDefinition* GetShorthand(const String& shorthand_name) const;