Review inline documentation to fix spelling and improve grammar

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 @@ public:
 	/// @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 @@ public:
 	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 @@ public:
 	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 @@ public:
 	/// @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 @@ public:
 
 	/// 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 @@ public:
 	/// 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 @@ public:
 	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 @@ public:
 	/// 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 @@ public:
 	/// @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 @@ private:
 	// 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 @@ private:
 
 	// 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,7 +77,7 @@ 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.
@@ -85,7 +85,7 @@ 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,7 +128,7 @@ 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.
@@ -136,8 +136,9 @@ RMLUICORE_API int GetNumContexts();
 /// 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.

Include/RmlUi/Core/DataModelHandle.h

@@ -90,7 +90,7 @@ public:
 	}
 
 	// Bind a user-declared DataVariable.
-	// For advanced use cases, for example for binding variables to a custom 'VariableDefinition'.
+	// For advanced use cases, such as binding variables to a custom 'VariableDefinition'.
 	bool BindCustomDataVariable(const String& name, DataVariable data_variable) { return BindVariable(name, data_variable); }
 
 	// Register a scalar type with associated get and set functions.
@@ -106,7 +106,7 @@ public:
 	template <typename T>
 	StructHandle<T> RegisterStruct();
 
-	// Register a user-declared VariableDefinition to describe a custom type behaviour.
+	// Register a user-declared VariableDefinition to describe a custom type behavior.
 	template <typename T>
 	bool RegisterCustomDataVariableDefinition(UniquePtr<VariableDefinition> definition);
 
@@ -143,7 +143,7 @@ private:
 template <typename T>
 inline bool DataModelConstructor::RegisterScalar(DataTypeGetFunc<T> get_func, DataTypeSetFunc<T> set_func)
 {
-	// Though enum is builtin scalar type, we allow custom getter/setter on it.
+	// We allow custom getters/setters for enums, even though they are considered builtin data scalars.
 	static_assert(!is_builtin_data_scalar<T>::value || std::is_enum<T>::value,
 		"Cannot register scalar data type function. Arithmetic types and String are handled internally and does not need to be registered.");
 	const FamilyId id = Family<T>::Id();

Include/RmlUi/Core/Element.h

@@ -232,8 +232,8 @@ public:
 	/// @return The value of this property for this element, or nullptr if this property has not been explicitly defined for this element.
 	const Property* GetLocalProperty(const String& name);
 	const Property* GetLocalProperty(PropertyId id);
-	/// Returns the local style properties, excluding any properties from local class.
-	/// @return The local properties for this element, or nullptr if no properties defined
+	/// Returns the local style properties. Does not include properties applied from any locally set classes.
+	/// @return The local properties for this element.
 	const PropertyMap& GetLocalStyleProperties();
 
 	/// Resolves a length to its canonical unit ('px').
@@ -250,13 +250,13 @@ public:
 
 	/// Returns the size of the containing block. Often percentages are scaled relative to this.
 	Vector2f GetContainingBlock();
-	/// Returns 'position' property value from element's computed values.
+	/// Returns 'position' property value from the element's computed values.
 	Style::Position GetPosition();
-	/// Returns 'float' property value from element's computed values.
+	/// Returns 'float' property value from the element's computed values.
 	Style::Float GetFloat();
-	/// Returns 'display' property value from element's computed values.
+	/// Returns 'display' property value from the element's computed values.
 	Style::Display GetDisplay();
-	/// Returns 'line-height' property value from element's computed values.
+	/// Returns 'line-height' property value from the element's computed values.
 	float GetLineHeight();
 
 	/// Project a 2D point in pixel coordinates onto the element's plane.
@@ -316,7 +316,7 @@ public:
 	Variant* GetAttribute(const String& name);
 	/// Gets the specified attribute.
 	const Variant* GetAttribute(const String& name) const;
-	/// Gets the specified attribute, with default value.
+	/// Gets the specified attribute, or the default value.
 	/// @param[in] name Name of the attribute to retrieve.
 	/// @param[in] default_value Value to return if the attribute doesn't exist.
 	template <typename T>
@@ -365,10 +365,10 @@ public:
 	/// @param[in] id The new id of the element.
 	void SetId(const String& id);
 
-	/// Gets the horizontal offset from the context's left edge to element's left border edge.
+	/// Gets the horizontal offset from the context's left edge to the element's left border edge.
 	/// @return The horizontal offset of the element within its context, in pixels.
 	float GetAbsoluteLeft();
-	/// Gets the vertical offset from the context's top edge to element's top border edge.
+	/// Gets the vertical offset from the context's top edge to the element's top border edge.
 	/// @return The vertical offset of the element within its context, in pixels.
 	float GetAbsoluteTop();
 
@@ -457,7 +457,7 @@ public:
 	/// @return The child element at the given index.
 	Element* GetChild(int index) const;
 	/// Get the current number of children in this element
-	/// @param[in] include_non_dom_elements True if the caller wants to include the non DOM children. Only set this to true if you know what you're
+	/// @param[in] include_non_dom_elements True if the caller wants to include the non-DOM children. Only set this to true if you know what you're
 	/// doing!
 	/// @return The number of children.
 	int GetNumChildren(bool include_non_dom_elements = false) const;
@@ -490,7 +490,7 @@ public:
 	/// Adds an event listener to this element.
 	/// @param[in] event Event to attach to.
 	/// @param[in] listener The listener object to be attached.
-	/// @param[in] in_capture_phase True to attach in the capture phase, false in bubble phase.
+	/// @param[in] in_capture_phase True to attach in the capture phase, false in the bubble phase.
 	/// @lifetime The added listener must stay alive until after the dispatched call from EventListener::OnDetach(). This occurs
 	///     e.g. when the element is destroyed or when RemoveEventListener() is called with the same parameters passed here.
 	void AddEventListener(const String& event, EventListener* listener, bool in_capture_phase = false);
@@ -516,7 +516,7 @@ public:
 	bool DispatchEvent(EventId id, const Dictionary& parameters);
 
 	/// Scrolls the parent element's contents so that this element is visible.
-	/// @param[in] options Scroll parameters that control desired element alignment relative to the parent.
+	/// @param[in] options Scroll parameters that control the desired element alignment relative to the parent.
 	void ScrollIntoView(ScrollIntoViewOptions options);
 	/// Scrolls the parent element's contents so that this element is visible.
 	/// @param[in] align_with_top If true, the element will align itself to the top of the parent element's window. If false, the element will be
@@ -525,7 +525,7 @@ public:
 	/// Sets the scroll offset of this element to the given coordinates.
 	/// @param[in] offset The scroll destination coordinates.
 	/// @param[in] behavior Smooth scrolling behavior.
-	/// @note Smooth scrolling can only be applied to a single element at a time, any active smooth scrolls will be cancelled.
+	/// @note Smooth scrolling can only be applied to a single element at a time, any active smooth scrolls will be canceled.
 	void ScrollTo(Vector2f offset, ScrollBehavior behavior = ScrollBehavior::Instant);
 
 	/// Append a child to this element.
@@ -589,7 +589,7 @@ public:
 	//@{
 	/// Access the event dispatcher for this element.
 	EventDispatcher* GetEventDispatcher() const;
-	/// Returns event types with number of listeners for debugging.
+	/// Returns event types with the number of listeners for debugging.
 	String GetEventDispatcherSummary() const;
 	/// Access the element background and border.
 	ElementBackgroundBorder* GetElementBackgroundBorder() const;

Include/RmlUi/Core/ElementDocument.h

@@ -127,18 +127,18 @@ public:
 	/// @return The next tabbable element, or nullptr if none could be found.
 	Element* FindNextTabElement(Element* current_element, bool forward);
 
-	/// Loads an inline script into the document. Note that the base implementation does nothing, scripting language addons hook this method.
+	/// Loads an inline script into the document. Note that the base implementation does nothing, but script plugins can hook into this method.
 	/// @param[in] content The script content.
 	/// @param[in] source_path Path of the script the source comes from, useful for debug information.
 	/// @param[in] source_line Line of the script the source comes from, useful for debug information.
 	virtual void LoadInlineScript(const String& content, const String& source_path, int source_line);
-	/// Loads an external script into the document. Note that the base implementation does nothing, scripting language addons hook this method.
+	/// Loads an external script into the document. Note that the base implementation does nothing, but script plugins can hook into this method.
 	/// @param[in] source_path The script file path.
 	virtual void LoadExternalScript(const String& source_path);
 
 	/// Updates the document, including its layout. Users must call this manually before requesting information such as
-	/// size or position of an element if any element in the document was recently changed, unless Context::Update has
-	/// already been called after the change. This has a performance penalty, only call when necessary.
+	/// the size or position of an element if any element in the document was recently changed, unless Context::Update
+	/// has already been called after the change. This has a performance penalty, only call when necessary.
 	void UpdateDocument();
 
 protected:
@@ -167,7 +167,7 @@ private:
 	/// Returns true if the document has been marked as needing a re-layout.
 	bool IsLayoutDirty() override;
 
-	/// Notify the document that media query related properties have changed and that style sheets need to be re-evaluated.
+	/// Notify the document that media query-related properties have changed and that style sheets need to be re-evaluated.
 	void DirtyMediaQueries();
 
 	/// Updates all sizes defined by the 'vw' and the 'vh' units.

Include/RmlUi/Core/ElementText.h

@@ -58,9 +58,9 @@ public:
 	/// @param[out] line_width The width (in pixels) of the generated line.
 	/// @param[in] line_begin The index of the first character to be rendered in the line.
 	/// @param[in] maximum_line_width The width (in pixels) of space allowed for the line, or -1 for unlimited space.
-	/// @param[in] right_spacing_width The width (in pixels) of the spacing (consisting of margins, padding, etc) that must be remaining on the right
+	/// @param[in] right_spacing_width The width (in pixels) of the spacing (consisting of margins, padding, etc.) that must be remaining on the right
 	/// of the line if the last of the text is rendered onto this line.
-	/// @param[in] trim_whitespace_prefix If we're collapsing whitespace, whether or not to remove all prefixing whitespace or collapse it down to a
+	/// @param[in] trim_whitespace_prefix If we're collapsing whitespace, true to remove all prefixing whitespace, or false to collapse it down to a
 	/// single space.
 	/// @param[in] decode_escape_characters Decode escaped characters such as & into &.
 	/// @param[in] allow_empty Allow no tokens to be consumed from the line.

Include/RmlUi/Core/ElementUtilities.h

@@ -76,7 +76,7 @@ public:
 	/// @param[in] class_name Class name to search for.
 	static void GetElementsByClassName(ElementList& elements, Element* root_element, const String& class_name);
 
-	/// Returns an element's density-independent pixel ratio, defined by it's context
+	/// Returns an element's density-independent pixel ratio, defined by its context.
 	/// @param[in] element The element to determine the density-independent pixel ratio for.
 	/// @return The density-independent pixel ratio of the context, or 1.0 if no context assigned.
 	static float GetDensityIndependentPixelRatio(Element* element);
@@ -128,7 +128,7 @@ public:
 	/// @param anchor[in] Defines which corner or edge the border is to be positioned relative to.
 	static bool PositionElement(Element* element, Vector2f offset, PositionAnchor anchor);
 
-	/// Applies an element's accumulated transform matrix, determined from its and ancestor's `perspective' and `transform' properties.
+	/// Applies an element's accumulated transform matrix, determined from the `perspective` and `transform` properties of itself and ancestors.
 	/// @param[in] element The element whose transform to apply, or nullptr for identity transform.
 	/// @return True if the transform could be submitted to the render interface.
 	static bool ApplyTransform(Element& element);

Include/RmlUi/Core/Elements/ElementFormControl.h

@@ -65,7 +65,7 @@ public:
 	/// @param[in] value The new value of the form control.
 	virtual void SetValue(const String& value) = 0;
 	/// Returns if this value should be submitted with the form.
-	/// @return True if the value should be be submitted with the form, false otherwise.
+	/// @return True if the value should be submitted with the form, false otherwise.
 	virtual bool IsSubmitted();
 
 	/// Returns the disabled status of the form control.

Include/RmlUi/Core/Elements/ElementFormControlSelect.h

@@ -59,7 +59,7 @@ public:
 	/// @param[in] value The new value of the form control.
 	void SetValue(const String& value) override;
 
-	/// Sets the index of the selection. If the new index lies outside of the bounds, it will be clamped.
+	/// Sets the index of the selection. If the new index lies outside the bounds, it will be clamped.
 	/// @param[in] selection The new selection index.
 	void SetSelection(int selection);
 	/// Returns the index of the currently selected item.
@@ -77,9 +77,9 @@ public:
 	/// Adds a new option to the select control.
 	/// @param[in] rml The RML content used to represent the option. This is usually a simple string, but can include RML tags.
 	/// @param[in] value The value of the option. This is used to identify the option, but does not necessarily need to be unique.
-	/// @param[in] before The index of the element to insert the new option before. If out of bounds of the control's option list (the default) the
+	/// @param[in] before The index of the element to insert the new option before. If out of bounds of the control's option list (the default), the
 	/// new option will be added at the end of the list.
-	/// @param[in] selectable If true this option can be selected. If false, this option is not selectable.
+	/// @param[in] selectable If true, this option can be selected. If false, this option is not selectable.
 	/// @return The index of the new option.
 	int Add(const String& rml, const String& value, int before = -1, bool selectable = true);
 	/// Adds a new option to the select control.
@@ -123,7 +123,7 @@ protected:
 	/// @return True.
 	bool GetIntrinsicDimensions(Vector2f& intrinsic_dimensions, float& intrinsic_ratio) override;
 
-	/// Respond to changed value attribute.
+	/// Respond to a change to the value attribute.
 	void OnAttributeChange(const ElementAttributes& changed_attributes) override;
 
 	void MoveChildren();

Include/RmlUi/Core/Elements/ElementFormControlTextArea.h

@@ -37,7 +37,7 @@ namespace Rml {
 class WidgetTextInputMultiLine;
 
 /**
-    Default RmlUi implemention of a text area.
+    Default RmlUi implementation of a text area.
 
     @author Peter Curry
  */
@@ -62,7 +62,7 @@ public:
 
 	/// Sets the number of characters visible across the text area. Note that this will only be precise when using
 	/// a fixed-width font.
-	/// @param[in] size The number of visible characters.
+	/// @param[in] num_columns The number of visible columns (characters).
 	void SetNumColumns(int num_columns);
 	/// Returns the approximate number of characters visible at once.
 	/// @return The number of visible characters.
@@ -132,7 +132,7 @@ protected:
 	void GetInnerRML(String& content) const override;
 
 private:
-	/// Sets the necessary properties to display the widget in current word wrap state.
+	/// Sets the necessary properties to display the widget in the current word wrap state.
 	void SetWordWrapProperties();
 
 	UniquePtr<WidgetTextInputMultiLine> widget;

Include/RmlUi/Core/Elements/ElementTabSet.h

@@ -47,16 +47,16 @@ public:
 	ElementTabSet(const String& tag);
 	~ElementTabSet();
 
-	/// Sets the specifed tab index's tab title RML.
+	/// Sets the specified tab index's tab title RML.
 	/// @param[in] tab_index The tab index to set. If it doesn't already exist, it will be created.
 	/// @param[in] rml The RML to set on the tab title.
 	void SetTab(int tab_index, const String& rml);
-	/// Sets the specifed tab index's tab panel RML.
+	/// Sets the specified tab index's tab panel RML.
 	/// @param[in] tab_index The tab index to set. If it doesn't already exist, it will be created.
 	/// @param[in] rml The RML to set on the tab panel.
 	void SetPanel(int tab_index, const String& rml);
 
-	/// Set the specifed tab index's title element.
+	/// Set the specified tab index's title element.
 	/// @param[in] tab_index The tab index to set. If it doesn't already exist, it will be created.
 	/// @param[in] element The root of the element tree to set as the tab title.
 	void SetTab(int tab_index, ElementPtr element);

Include/RmlUi/Core/Factory.h

@@ -62,9 +62,6 @@ enum class EventId : uint16_t;
 /**
     The Factory contains a registry of instancers for different types.
 
-    All instantiation of these rmlui types should go through the factory
-    so that scripting API's can bind in new types.
-
     @author Lloyd Weehuizen
  */
 
@@ -165,7 +162,7 @@ public:
 	static SharedPtr<StyleSheetContainer> InstanceStyleSheetStream(Stream* stream);
 	/// Clears the style sheet cache. This will force style sheets to be reloaded.
 	static void ClearStyleSheetCache();
-	/// Clears the template cache. This will force template to be reloaded.
+	/// Clears the template cache. This will force templates to be reloaded.
 	static void ClearTemplateCache();
 
 	/// Registers an instancer for all events.
@@ -193,15 +190,15 @@ public:
 	/// Register an instancer for data views.
 	/// Structural views start a special XML parsing procedure when encountering a declaration of the view. Instead of instancing
 	/// children elements, the raw inner XML/RML contents are submitted to the initializing procedure of the view.
-	/// @param[in] instancer  The instancer to be called.
-	/// @param[in] type_name  The type name of the view, determines the element attribute that is used to initialize it.
+	/// @param[in] instancer The instancer to be called.
+	/// @param[in] type_name The type name of the view, determines the element attribute used to initialize it.
 	/// @param[in] is_structural_view  Set true if the view should be parsed as a structural view.
 	/// @lifetime The instancer must be kept alive until after the call to Rml::Shutdown.
 	static void RegisterDataViewInstancer(DataViewInstancer* instancer, const String& type_name, bool is_structural_view = false);
 
 	/// Register an instancer for data controllers.
-	/// @param[in] instancer  The instancer to be called.
-	/// @param[in] type_name  The type name of the controller, determines the element attribute that is used to initialize it.
+	/// @param[in] instancer The instancer to be called.
+	/// @param[in] type_name The type name of the controller, determines the element attribute used to initialize it.
 	/// @lifetime The instancer must be kept alive until after the call to Rml::Shutdown.
 	static void RegisterDataControllerInstancer(DataControllerInstancer* instancer, const String& type_name);
 

Include/RmlUi/Core/Filter.h

@@ -55,7 +55,7 @@ public:
 	/// 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 filters active on the current element.
+	/// @note Modifying the ink overflow rectangle affects the 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/Log.h

@@ -59,7 +59,7 @@ public:
 
 	/// Log a parse error on the specified file and line number.
 	/// @param[in] filename Name of the file with the parse error.
-	/// @param[in] line_number Line the error occured on.
+	/// @param[in] line_number Line the error occurred on.
 	/// @param[in] format The error message, with sprintf-style parameters.
 	static void ParseError(const String& filename, int line_number, const char* format, ...) RMLUI_ATTRIBUTE_FORMAT_PRINTF(3, 4);
 };

Include/RmlUi/Core/Math.h

@@ -95,21 +95,21 @@ namespace Math {
 	/// Color interpolation.
 	RMLUICORE_API ColourbPremultiplied RoundedLerp(float t, ColourbPremultiplied c0, ColourbPremultiplied c1);
 
-	/// Evaluates if a number is, or close to, zero.
+	/// Evaluates if a number is zero or close to it.
 	/// @param[in] value The number to compare to zero.
 	/// @return True if the number is zero or close to it, false otherwise.
 	RMLUICORE_API bool IsCloseToZero(float value);
 
 	/// Calculates the absolute value of a number.
-	/// @param[in] value The number of get the absolute value of.
+	/// @param[in] value The number to get the absolute value of.
 	/// @return The absolute value of the number.
 	RMLUICORE_API float Absolute(float value);
 	/// Calculates the absolute value of a number.
-	/// @param[in] value The number of get the absolute value of.
+	/// @param[in] value The number to get the absolute value of.
 	/// @return The absolute value of the number.
 	RMLUICORE_API int Absolute(int value);
 	/// Calculates the component-wise absolute value of a vector.
-	/// @param[in] value The vector of get the absolute value of.
+	/// @param[in] value The vector to get the absolute value of.
 	/// @return The absolute value of the vector.
 	RMLUICORE_API Vector2f Absolute(Vector2f value);
 
@@ -131,7 +131,7 @@ namespace Math {
 	RMLUICORE_API float ASin(float value);
 	/// Calculates the tangent of an angle.
 	/// @param[in] angle The angle to calculate the tangent of, in radians.
-	/// @return The tanget of the angle.
+	/// @return The tangent of the angle.
 	RMLUICORE_API float Tan(float angle);
 	/// Calculates the angle of a two-dimensional line.
 	/// @param[in] y The y-component of the line.
@@ -194,7 +194,7 @@ namespace Math {
 	/// @return The rounded integer.
 	RMLUICORE_API int RoundDownToInteger(float value);
 
-	/// Decompose floating-point value to its fractional and integral parts.
+	/// Decomposes a floating-point value to its fractional and integral parts.
 	/// @param[in] value The value to decompose.
 	/// @param[out] integral The integral part of the value.
 	/// @return The fractional part of the value.
@@ -224,7 +224,7 @@ namespace Math {
 	/// @return The smallest power of two that is as least as big as the input value.
 	RMLUICORE_API int ToPowerOfTwo(int value);
 
-	/// Converts from the ASCII-representation of a hexadecimal digit to decimal.
+	/// Converts from the ASCII representation of a hexadecimal digit to decimal.
 	/// @param[in] hex_digit The hexadecimal digit to convert to decimal.
 	/// @return The digit in decimal.
 	RMLUICORE_API int HexToDecimal(char hex_digit);
@@ -237,7 +237,7 @@ namespace Math {
 	/// @param[in] max_value The limit to random value. The generated value will be guaranteed to be below this limit.
 	/// @return The random value.
 	RMLUICORE_API int RandomInteger(int max_value);
-	/// Generates a random boolean value, with equal chance of true or false.
+	/// Generates a random boolean value, with an equal chance of true or false.
 	/// @return The random value.
 	RMLUICORE_API bool RandomBool();
 

Include/RmlUi/Core/RenderInterface.h

@@ -93,7 +93,7 @@ public:
 	virtual void ReleaseTexture(TextureHandle texture) = 0;
 
 	/// Called by RmlUi when it wants to enable or disable scissoring to clip content.
-	/// @param[in] enable True if scissoring is to enabled, false if it is to be disabled.
+	/// @param[in] enable True to enable scissoring, false to disable it.
 	virtual void EnableScissorRegion(bool enable) = 0;
 	/// Called by RmlUi when it wants to change the scissor region.
 	/// @param[in] region The region to be rendered. All pixels outside this region should be clipped.
@@ -105,7 +105,7 @@ public:
 	 */
 
 	/// Called by RmlUi when it wants to enable or disable the clip mask.
-	/// @param[in] enable True if the clip mask is to be enabled, false if it is to be disabled.
+	/// @param[in] enable True to enable the clip mask, false to disable it.
 	virtual void EnableClipMask(bool enable);
 	/// Called by RmlUi when it wants to set or modify the contents of the clip mask.
 	/// @param[in] operation Describes how the geometry should affect the clip mask.
@@ -113,7 +113,7 @@ public:
 	/// @param[in] translation The translation to apply to the geometry.
 	/// @note When enabled, the clip mask should hide any rendered contents outside the area of the mask.
 	/// @note The clip mask applies exclusively to all other functions that render with a geometry handle, in addition
-	/// to the layer compositing function while rendering to its destination.
+	/// to the `CompositeLayers` function while rendering to its destination.
 	virtual void RenderToClipMask(ClipMaskOperation operation, CompiledGeometryHandle geometry, Vector2f translation);
 
 	/// Called by RmlUi when it wants the renderer to use a new transform matrix.

Include/RmlUi/Core/Transform.h

@@ -42,7 +42,7 @@ class Property;
 
     The class holds a list of transform primitives making up a complete transformation specification
     of an element. Each transform instance is relative to the element's parent coordinate system.
-    During the Context::Render call the transforms of the current element and its ancestors will be
+    During the Context::Render call, the transforms of the current element and its ancestors will be
     used to find the final transformation matrix for the global coordinate system.
 
     @author Markus Schöngart

Samples/basic/data_binding/data/data_binding.rml

@@ -374,7 +374,7 @@ select selectbox option.disabled {
 			<li style="color: red;" data-if="pizza && rating < 70">• You can only have pizza if the rating is satisfactory.</li>
 			<li data-if="pizza && rating >= 70">• Pizza is life!</li>
 			<li data-if="pasta">• Pasta is squiggly good!</li>
-			<li data-if="lasagne">• Lasagne is delicous!</li>
+			<li data-if="lasagne">• Lasagne is delicious!</li>
 		</div>
 		<h2>Subject</h2>
 		<div>

Samples/basic/demo/data/demo.rml

@@ -660,7 +660,7 @@ form .nav-auto, form input.checkbox, form input.radio
 		<div style="width: 96dp; height: 85dp; decorator: image( demo-title-bar );"/>
 		<div style="width: 250dp; height: 85dp; decorator: tiled-horizontal( title-bar-l, title-bar-c, title-bar-r );"/>
 	</div>
-	<p>In the third example we show the same title bar that is used to style the sample windows.</p>
+	<p>In the third example we show the same title bar used to style the sample windows.</p>
 
 
 	<h1>Tiled-vertical decorator</h1>
@@ -902,7 +902,7 @@ form .nav-auto, form input.checkbox, form input.radio
 		<col/>
 		<tr id="row_source">
 			<td><textarea id="sandbox_rml_source" wrap="nowrap" onchange="set_sandbox_body"></textarea></td>
-			<td id="vertical_slider"><handle class="slider"size_target="col_rml_source"/></td>
+			<td id="vertical_slider"><handle class="slider" size_target="col_rml_source"/></td>
 			<td><textarea id="sandbox_rcss_source" wrap="nowrap" onchange="set_sandbox_style"></textarea></td>
 		</tr>
 		<tr>