Merge "(bug 1) document Skin::buildSidebar per own experience"

diff --combined includes/Skin.php
index 9e5613e,94845b7..4889863
--- 1/includes/Skin.php
--- 2/includes/Skin.php
+++ b/includes/Skin.php
@@@ -73,7 -73,7 +73,7 @@@ abstract class Skin extends ContextSour
                return $wgValidSkinNames;
        }
  
 -      /**
 +      /**
         * Fetch the skinname messages for available skins.
         * @return array of strings
         */
@@@ -1132,7 -1132,23 +1132,23 @@@
        }
  
        /**
-        * Build an array that represents the sidebar(s), the navigation bar among them
+        * Build an array that represents the sidebar(s), the navigation bar among them.
+        *
+        * BaseTemplate::getSidebar can be used to simplify the format and id generation in new skins.
+        *
+        * The format of the returned array is array( heading => content, ... ), where:
+        * - heading is the heading of a navigation portlet. It is either:
+        *   - magic string to be handled by the skins ('SEARCH' / 'LANGUAGES' / 'TOOLBOX' / ...)
+        *   - a message name (e.g. 'navigation'), the message should be HTML-escaped by the skin
+        *   - plain text, which should be HTML-escaped by the skin
+        * - content is the contents of the portlet. It is either:
+        *   - HTML text (<ul><li>...</li>...</ul>)
+        *   - array of link data in a format accepted by BaseTemplate::makeListItem()
+        *   - (for a magic string as a key, any value)
+        *
+        * Note that extensions can control the sidebar contents using the SkinBuildSidebar hook
+        * and can technically insert anything in here; skin creators are expected to handle
+        * values described above.
         *
         * @return array
         */