Review inline documentation to fix spelling and improve grammar

Author: mikke89

Backends/RmlUi_Renderer_GL3.cpp

@@ -1089,8 +1089,8 @@ void RenderInterface_GL3::ReleaseGeometry(Rml::CompiledGeometryHandle handle)
 	delete geometry;
 }
 
-/// Flip vertical axis of the rectangle, and move its origin to the vertically opposite side of the viewport.
-/// @note Changes coordinate system from RmlUi to OpenGL, or equivalently in reverse.
+/// Flip the vertical axis of the rectangle, and move its origin to the vertically opposite side of the viewport.
+/// @note Changes the coordinate system from RmlUi to OpenGL, or equivalently in reverse.
 /// @note The Rectangle::Top and Rectangle::Bottom members will have reverse meaning in the returned rectangle.
 static Rml::Rectanglei VerticallyFlipped(Rml::Rectanglei rect, int viewport_height)
 {

Include/RmlUi/Core/Colour.h

@@ -79,7 +79,7 @@ class Colour {
 	/// @param[in] rhs The colour to subtract.
 	inline void operator-=(Colour rhs);
 	/// Scales this colour component-wise in-place.
-	/// @param[in] rhs The value to scale this colours's components by.
+	/// @param[in] rhs The value to scale this colour's components by.
 	inline void operator*=(float rhs);
 	/// Scales this colour component-wise in-place by the inverse of a value.
 	/// @param[in] rhs The value to divide this colour's components by.

Include/RmlUi/Core/Context.h

@@ -51,7 +51,7 @@ class TextInputHandler;
 enum class EventId : uint16_t;
 
 /**
-    A context for storing, rendering and processing RML documents. Multiple contexts can exist simultaneously.
+    A context for storing, rendering, and processing RML documents. Multiple contexts can exist simultaneously.
 
     @author Peter Curry
  */
@@ -85,7 +85,7 @@ class RMLUICORE_API Context : public ScriptInterface {
 	float GetDensityIndependentPixelRatio() const;
 
 	/// Updates all elements in the context's documents.
-	/// This must be called before Context::Render, but after any elements have been changed, added or removed.
+	/// This must be called before Context::Render, but after any elements have been changed, added, or removed.
 	bool Update();
 	/// Renders all visible elements in the context's documents.
 	bool Render();
@@ -117,7 +117,7 @@ class RMLUICORE_API Context : public ScriptInterface {
 	void UnloadAllDocuments();
 
 	/// Enable or disable handling of the mouse cursor from this context.
-	/// When enabled, changes to the cursor name is transmitted through the system interface.
+	/// When enabled, changes to the cursor name are passed to the system interface.
 	/// @param[in] enable True to enable mouse cursor handling, false to disable.
 	void EnableMouseCursor(bool enable);
 
@@ -151,11 +151,11 @@ class RMLUICORE_API Context : public ScriptInterface {
 	/// @return The root element.
 	Element* GetRootElement();
 
-	// Returns the youngest descendent of the given element which is under the given point in screen coordinates.
-	// @param[in] point The point to test.
-	// @param[in] ignore_element If set, this element and its descendents will be ignored.
-	// @param[in] element Used internally.
-	// @return The element under the point, or nullptr if nothing is.
+	/// Returns the youngest descendent of the given element which is under the given point in screen coordinates.
+	/// @param[in] point The point to test.
+	/// @param[in] ignore_element If set, this element and its descendents will be ignored.
+	/// @param[in] element Used internally.
+	/// @return The element under the point, or nullptr if nothing is.
 	Element* GetElementAtPoint(Vector2f point, const Element* ignore_element = nullptr, Element* element = nullptr) const;
 
 	/// Brings the document to the front of the document stack.
@@ -181,19 +181,19 @@ class RMLUICORE_API Context : public ScriptInterface {
 
 	/// Sends a key down event into this context.
 	/// @param[in] key_identifier The key pressed.
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the event was not consumed (ie, was prevented from propagating by an element), false if it was.
 	bool ProcessKeyDown(Input::KeyIdentifier key_identifier, int key_modifier_state);
 	/// Sends a key up event into this context.
 	/// @param[in] key_identifier The key released.
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the event was not consumed (ie, was prevented from propagating by an element), false if it was.
 	bool ProcessKeyUp(Input::KeyIdentifier key_identifier, int key_modifier_state);
 
-	/// Sends a single unicode character as text input into this context.
-	/// @param[in] character The unicode code point to send into this context.
+	/// Sends a single Unicode character as text input into this context.
+	/// @param[in] character The Unicode code point to send into this context.
 	/// @return True if the event was not consumed (ie, was prevented from propagating by an element), false if it was.
 	bool ProcessTextInput(Character character);
 	/// Sends a single ascii character as text input into this context.
@@ -206,19 +206,19 @@ class RMLUICORE_API Context : public ScriptInterface {
 	/// Sends a mouse movement event into this context.
 	/// @param[in] x The x-coordinate of the mouse cursor, in window-coordinates (ie, 0 should be the left of the client area).
 	/// @param[in] y The y-coordinate of the mouse cursor, in window-coordinates (ie, 0 should be the top of the client area).
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the mouse is not interacting with any elements in the context (see 'IsMouseInteracting'), otherwise false.
 	bool ProcessMouseMove(int x, int y, int key_modifier_state);
 	/// Sends a mouse-button down event into this context.
-	/// @param[in] button_index The index of the button that was pressed; 0 for the left button, 1 for right, and 2 for middle button.
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] button_index The index of the button that was pressed. Left: 0, Right: 1, Middle: 2.
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the mouse is not interacting with any elements in the context (see 'IsMouseInteracting'), otherwise false.
 	bool ProcessMouseButtonDown(int button_index, int key_modifier_state);
 	/// Sends a mouse-button up event into this context.
-	/// @param[in] button_index The index of the button that was release; 0 for the left button, 1 for right, and 2 for middle button.
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] button_index The index of the button that was release. Left: 0, Right: 1, Middle: 2.
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the mouse is not interacting with any elements in the context (see 'IsMouseInteracting'), otherwise false.
 	bool ProcessMouseButtonUp(int button_index, int key_modifier_state);
@@ -227,14 +227,14 @@ class RMLUICORE_API Context : public ScriptInterface {
 	bool ProcessMouseWheel(float wheel_delta, int key_modifier_state);
 	/// Sends a mousescroll event into this context, and scrolls the document unless the event was stopped from propagating.
 	/// @param[in] wheel_delta The mouse-wheel movement this frame, with positive values being directed right and down.
-	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc) keys; this should be generated by ORing together
+	/// @param[in] key_modifier_state The state of key modifiers (shift, control, caps-lock, etc.) keys; this should be generated by ORing together
 	/// members of the Input::KeyModifier enumeration.
 	/// @return True if the event was not consumed (ie, was prevented from propagating by an element), false if it was.
 	bool ProcessMouseWheel(Vector2f wheel_delta, int key_modifier_state);
 	/// Tells the context the mouse has left the window. This removes any hover state from all elements and prevents 'Update()' from setting the hover
 	/// state for elements under the mouse.
 	/// @return True if the mouse is not interacting with any elements in the context (see 'IsMouseInteracting'), otherwise false.
-	/// @note The mouse is considered activate again after the next call to 'ProcessMouseMove()'.
+	/// @note The mouse is considered activated again after the next call to 'ProcessMouseMove()'.
 	bool ProcessMouseLeave();
 
 	/// Returns a hint on whether the mouse is currently interacting with any elements in this context, based on previously submitted
@@ -252,7 +252,7 @@ class RMLUICORE_API Context : public ScriptInterface {
 	/// Retrieves the render manager which can be used to submit changes to the render state.
 	RenderManager& GetRenderManager();
 
-	/// Obtains the text input handler.
+	/// Retrieves the text input handler.
 	TextInputHandler* GetTextInputHandler() const;
 
 	/// Sets the instancer to use for releasing this object.
@@ -271,32 +271,29 @@ class RMLUICORE_API Context : public ScriptInterface {
 	/// @return A constructor for the data model, or empty if it could not be found.
 	DataModelConstructor GetDataModel(const String& name);
 	/// Removes the given data model.
-	/// This also removes all data views, controllers and bindings contained by the data model.
+	/// This also removes all data views, controllers, and bindings contained by the data model.
 	/// @warning Invalidates all handles and constructors pointing to the data model.
 	/// @param[in] name The name of the data model.
-	/// @return True if succesfully removed, false if no data model was found.
+	/// @return True if successfully removed, false if no data model was found.
 	bool RemoveDataModel(const String& name);
 
-	/// This will set the documents base <tag> before creation. Default = "body"
+	/// Sets the base tag name of documents before creation. Default: "body".
 	/// @param[in] tag The name of the base tag. Example: "html"
 	void SetDocumentsBaseTag(const String& tag);
-	/// Gets the name of the documents base tag.
-	/// @return The current documents base tag name.
+	/// Gets the base tag name of documents.
+	/// @return The current base tag name of documents.
 	const String& GetDocumentsBaseTag();
 
-	/// Updates the time until Update should get called again. This can be used by elements
-	/// and the app to implement on demand rendering and thus drastically save CPU/GPU and
-	/// reduce power consumption during inactivity. The context stores the lowest requested
-	/// timestamp, which can later retrieved using GetNextUpdateDelay().
-	/// @param[in] delay Maximum time until next update
+	/// Updates the time until Update() should get called again. This can be used by elements and the application to
+	/// implement on-demand rendering and thus drastically save CPU/GPU and reduce power consumption during inactivity.
+	/// The context stores the lowest requested timestamp, which can later be retrieved using GetNextUpdateDelay().
+	/// @param[in] delay Maximum time until next update.
 	void RequestNextUpdate(double delay);
-
-	/// Get the max delay until update and render should get called again. An application can choose
-	/// to only call update and render once the time has elapsed, but theres no harm in doing so
-	/// more often. The returned value can be infinity, in which case update should be invoked after
-	/// user input was received. A value of 0 means "render as fast as possible", for example if
-	/// an animation is playing.
-	/// @return Time until next update is expected.
+	/// Get the max delay until Update() and Render() should get called again. An application can choose to only call
+	/// update and render once the time has elapsed, but there's no harm in doing so more often. The returned value can
+	/// be infinity, in which case Update() should be invoked after user input was received. A value of 0 means "render
+	/// as fast as possible", for example if an animation is playing.
+	/// @return Time until the next update is expected.
 	double GetNextUpdateDelay() const;
 
 protected:
@@ -365,7 +362,7 @@ class RMLUICORE_API Context : public ScriptInterface {
 	// Used when dragging a cloned object.
 	Element* drag_clone;
 
-	// The element currently being dragged over; this is equivalent to hover, but only set while an element is being
+	// The element currently being dragged over. This is equivalent to hover, but only set while an element is being
 	// dragged, and excludes the dragged element.
 	Element* drag_hover;
 	// Set of elements that are currently being dragged over; this differs from the hover state as the dragged element
@@ -397,7 +394,7 @@ class RMLUICORE_API Context : public ScriptInterface {
 
 	// Creates the drag clone from the given element. The old drag clone will be released if necessary.
 	void CreateDragClone(Element* element);
-	// Releases the drag clone, if one exists.
+	// Releases the drag clone if one exists.
 	void ReleaseDragClone();
 
 	// Scroll the target by the given amount, using smooth scrolling.

Include/RmlUi/Core/Core.h

@@ -60,7 +60,7 @@ RMLUICORE_API void Shutdown();
 /// @return The version number.
 RMLUICORE_API String GetVersion();
 
-/// Sets the interface through which all system requests are made. This is not required to be called, but if it is it
+/// Sets the interface through which all system requests are made. This is not required to be called, but if it is, it
 /// must be called before Initialise().
 /// @param[in] system_interface A non-owning pointer to the application-specified logging interface.
 /// @lifetime The interface must be kept alive until after the call to Rml::Shutdown.
@@ -77,15 +77,15 @@ RMLUICORE_API void SetRenderInterface(RenderInterface* render_interface);
 /// Returns RmlUi's default's render interface.
 RMLUICORE_API RenderInterface* GetRenderInterface();
 
-/// Sets the interface through which all file I/O requests are made. This is not required to be called, but if it is it
+/// Sets the interface through which all file I/O requests are made. This is not required to be called, but if it is, it
 /// must be called before Initialise().
 /// @param[in] file_interface A non-owning pointer to the application-specified file interface.
 /// @lifetime The interface must be kept alive until after the call to Rml::Shutdown.
 RMLUICORE_API void SetFileInterface(FileInterface* file_interface);
 /// Returns RmlUi's file interface.
 RMLUICORE_API FileInterface* GetFileInterface();
 
-/// Sets the interface through which all font requests are made. This is not required to be called, but if it is
+/// Sets the interface through which all font requests are made. This is not required to be called, but if it is,
 /// it must be called before Initialise().
 /// @param[in] font_interface A non-owning pointer to the application-specified font engine interface.
 /// @lifetime The interface must be kept alive until after the call to Rml::Shutdown.
@@ -108,13 +108,13 @@ RMLUICORE_API TextInputHandler* GetTextInputHandler();
 /// @param[in] text_input_handler The custom text input handler to use, or nullptr to use the default.
 /// @lifetime If specified, the render interface and the text input handler must be kept alive until after the call to
 ///           Rml::Shutdown. Alternatively, the render interface can be destroyed after all contexts it belongs to have been
-///           destroyed and a subsequent call has been made to Rml::ReleaseRenderManagers.
+///           destroyed, and a subsequent call has been made to Rml::ReleaseRenderManagers.
 /// @return A non-owning pointer to the new context, or nullptr if the context could not be created.
 RMLUICORE_API Context* CreateContext(const String& name, Vector2i dimensions, RenderInterface* render_interface = nullptr,
 	TextInputHandler* text_input_handler = nullptr);
 /// Removes and destroys a context.
 /// @param[in] name The name of the context to remove.
-/// @return True if name is a valid context, false otherwise.
+/// @return True if the name is a valid context, false otherwise.
 RMLUICORE_API bool RemoveContext(const String& name);
 /// Fetches a previously constructed context by name.
 /// @param[in] name The name of the desired context.
@@ -128,16 +128,17 @@ RMLUICORE_API Context* GetContext(int index);
 /// @return The total number of active RmlUi contexts.
 RMLUICORE_API int GetNumContexts();
 
-/// Adds a new font face to the font engine. The face's family, style and weight will be determined from the face itself.
+/// Adds a new font face to the font engine. The face's family, style, and weight will be determined from the face itself.
 /// @param[in] file_path The path to the file to load the face from. The path is passed directly to the file interface which is used to load the file.
 /// The default file interface accepts both absolute paths and paths relative to the working directory.
 /// @param[in] fallback_face True to use this font face for unknown characters in other font faces.
 /// @param[in] weight The weight to load when the font face contains multiple weights, otherwise the weight to register the font as. By default, it
 /// loads all found font weights.
 /// @param[in] face_index The index of the font face within a font collection.
 /// @return True if the face was loaded successfully, false otherwise.
-RMLUICORE_API bool LoadFontFace(const String& file_path, bool fallback_face = false, Style::FontWeight weight = Style::FontWeight::Auto, int face_index = 0);
-/// Adds a new font face from memory to the font engine. The face's family, style and weight is given by the parameters.
+RMLUICORE_API bool LoadFontFace(const String& file_path, bool fallback_face = false, Style::FontWeight weight = Style::FontWeight::Auto,
+	int face_index = 0);
+/// Adds a new font face from memory to the font engine. The face's family, style, and weight are given by the parameters.
 /// @param[in] data The font data.
 /// @param[in] family The family to register the font as.
 /// @param[in] style The style to register the font as.