Improve Html/Xml element generation docs

Corrects some docs to match actual behavior + clarifies what
syntax is allowed for attributes.

Change-Id: I45b27bc4d536063c508d902f592ad4d0dc265ed3

diff --git a/includes/Html.php b/includes/Html.php
index 972f62d..8fe4dbe 100644 (file)
--- a/includes/Html.php
+++ b/includes/Html.php
@@ -220,8 +220,10 @@ class Html {
         * Identical to rawElement(), but HTML-escapes $contents (like
         * Xml::element()).
         *
-        * @param string $element
-        * @param array $attribs
+        * @param string $element Name of the element, e.g., 'a'
+        * @param array $attribs Associative array of attributes, e.g., [
+        *   'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for
+        *   further documentation.
         * @param string $contents
         *
         * @return string
@@ -239,8 +241,10 @@ class Html {
         * Identical to rawElement(), but has no third parameter and omits the end
         * tag (and the self-closing '/' in XML mode for empty elements).
         *
-        * @param string $element
-        * @param array $attribs
+        * @param string $element Name of the element, e.g., 'a'
+        * @param array $attribs Associative array of attributes, e.g., [
+        *   'href' => 'https://www.mediawiki.org/' ]. See expandAttributes() for
+        *   further documentation.
         *
         * @return string
         */
@@ -459,7 +463,7 @@ class Html {
         *
         * @param array $attribs Associative array of attributes, e.g., [
         *   'href' => 'https://www.mediawiki.org/' ].  Values will be HTML-escaped.
-        *   A value of false means to omit the attribute.  For boolean attributes,
+        *   A value of false or null means to omit the attribute.  For boolean attributes,
         *   you can omit the key, e.g., [ 'checked' ] instead of
         *   [ 'checked' => 'checked' ] or such.
         *

diff --git a/includes/Xml.php b/includes/Xml.php
index 8f18046..d24a27c 100644 (file)
--- a/includes/Xml.php
+++ b/includes/Xml.php
@@ -59,8 +59,8 @@ class Xml {
         * Given an array of ('attributename' => 'value'), it generates the code
         * to set the XML attributes : attributename="value".
         * The values are passed to Sanitizer::encodeAttribute.
-        * Return null if no attributes given.
-        * @param array $attribs Array of attributes for an XML element
+        * Returns null or empty string if no attributes given.
+        * @param array|null $attribs Array of attributes for an XML element
         * @throws MWException
         * @return null|string
         */