Update documentation on operations that take node name and namespace …

…matchers.

lib/src/xml/extensions/find.dart

@@ -7,16 +7,15 @@ extension XmlFindExtension on XmlNode {
   /// Return a lazy [Iterable] of the _direct_ child elements in document
   /// order with the specified tag `name` and `namespace`.
   ///
-  /// Both `name` and `namespace` can be set to a specific [String] or `'*'` to
-  /// match anything. If no `namespace` is provided, the _fully qualified_ name
-  /// will be matched, otherwise only the _local name_ is compared.
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
   ///
   /// For example:
-  /// - `element.findElements('xsd:annotation')` finds all direct child elements
-  ///   with the fully qualified tag name `xsd:annotation`.
-  /// - `element.findElements('annotation', namespace: '*')` finds all direct
-  ///   child elements with the local tag name `annotation` no matter their
-  ///   namespace.
+  /// - `element.findElements('xsd:name')` finds all direct child elements with
+  ///   the fully qualified tag name `xsd:name`.
+  /// - `element.findElements('name', namespace: '*')` finds all direct child
+  ///   elements with the local tag name `name` no matter their namespace.
   /// - `element.findElements('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
   ///   finds all direct child elements within the provided namespace URI.
   ///
@@ -26,15 +25,15 @@ extension XmlFindExtension on XmlNode {
   /// Return a lazy [Iterable] of the _recursive_ child elements in document
   /// order with the specified tag `name`.
   ///
-  /// Both `name` and `namespace` can be set to a specific [String] or `'*'` to
-  /// match anything. If no `namespace` is provided, the _fully qualified_ name
-  /// will be matched, otherwise only the _local name_ is compared.
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
   ///
   /// For example:
-  /// - `document.findAllElements('xsd:annotation')` finds all elements with the
-  ///   fully qualified tag name `xsd:annotation`.
-  /// - `document.findAllElements('annotation', namespace: '*')` finds all
-  ///   elements with the local tag name `annotation` no matter their namespace.
+  /// - `document.findAllElements('xsd:name')` finds all elements with the fully
+  ///   qualified tag name `xsd:name`.
+  /// - `document.findAllElements('name', namespace: '*')` finds all elements
+  ///   with the local tag name `name` no matter their namespace.
   /// - `document.findAllElements('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
   ///   finds all elements with the given namespace URI.
   ///

lib/src/xml/mixins/has_attributes.dart

@@ -11,18 +11,73 @@ mixin XmlAttributesBase {
   List<XmlAttribute> get attributes => const [];
 
   /// Return the attribute value with the given `name`, or `null`.
+  ///
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
+  ///
+  /// For example:
+  /// - `element.getAttribute('xsd:name')` returns the first attribute value
+  ///   with the fully qualified attribute name `xsd:name`.
+  /// - `element.getAttribute('name', namespace: '*')` returns the first
+  ///   attribute value with the local attribute name `name` no matter the
+  ///   namespace.
+  /// - `element.getAttribute('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
+  ///  returns the first attribute value within the provided namespace URI.
+  ///
   String? getAttribute(String name, {String? namespace}) => null;
 
   /// Return the attribute node with the given `name`, or `null`.
+  ///
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
+  ///
+  /// For example:
+  /// - `element.getAttributeNode('xsd:name')` returns the first attribute node
+  ///   with the fully qualified attribute name `xsd:name`.
+  /// - `element.getAttributeNode('name', namespace: '*')` returns the first
+  ///   attribute node with the local attribute name `name` no matter the
+  ///   namespace.
+  /// - `element.getAttributeNode('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
+  ///  returns the first attribute node within the provided namespace URI.
+  ///
   XmlAttribute? getAttributeNode(String name, {String? namespace}) => null;
 
   /// Set the attribute value with the given fully qualified `name` to `value`.
   /// If an attribute with the name already exist, its value is updated.
   /// If the value is `null`, the attribute is removed.
+  ///
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
+  ///
+  /// For example:
+  /// - `element.setAttribute('xsd:name', 'value')` updates the attribute with
+  ///   the fully qualified attribute name `xsd:name`.
+  /// - `element.setAttribute('name', 'value', namespace: '*')` updates the
+  ///   attribute with the local attribute name `name` no matter the
+  ///   namespace.
+  /// - `element.setAttribute('*', 'value', namespace: 'http://www.w3.org/2001/XMLSchema')`
+  ///   updates the attribute within the provided namespace URI.
+  ///
   void setAttribute(String name, String? value, {String? namespace}) =>
       throw UnsupportedError('$this has no attributes');
 
   /// Removes the attribute value with the given fully qualified `name`.
+  ///
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
+  ///
+  /// For example:
+  /// - `element.removeAttribute('xsd:name')` removes the attribute with the
+  ///   fully qualified attribute name `xsd:name`.
+  /// - `element.removeAttribute('name', namespace: '*')` removes the attribute
+  ///   with the local attribute name `name` no matter the namespace.
+  /// - `element.removeAttribute('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
+  ///   removes the attribute within the provided namespace URI.
+  ///
   void removeAttribute(String name, {String? namespace}) =>
       setAttribute(name, null, namespace: namespace);
 }

lib/src/xml/mixins/has_children.dart

@@ -12,6 +12,19 @@ mixin XmlChildrenBase {
   Iterable<XmlElement> get childElements => const [];
 
   /// Return the first child element with the given `name`, or `null`.
+  ///
+  /// Both `name` and `namespace` can be a specific [String]; or `'*'` to match
+  /// anything. If no `namespace` is provided, the _fully qualified_ name is
+  /// compared; otherwise only the _local name_ is considered.
+  ///
+  /// For example:
+  /// - `element.getElement('xsd:name')` returns the first element with the
+  ///   fully qualified tag name `xsd:name`.
+  /// - `element.getElement('name', namespace: '*')` returns the first element
+  ///   with the local tag name `name` no matter the namespace.
+  /// - `element.getElement('*', namespace: 'http://www.w3.org/2001/XMLSchema')`
+  ///   returns the first element within the provided namespace URI.
+  ///
   XmlElement? getElement(String name, {String? namespace}) => null;
 
   /// Return the first child of this node, or `null` if there are no children.