Merge "Less wild whitespace"

[lhc/web/wiklou.git] / includes / Skin.php

diff --git a/includes/Skin.php b/includes/Skin.php
index 24d48bc..4889863 100644 (file)
--- a/includes/Skin.php
+++ b/includes/Skin.php
@@ -73,7 +73,7 @@ abstract class Skin extends ContextSource {
                return $wgValidSkinNames;
        }
 
-       /**
+       /**
         * Fetch the skinname messages for available skins.
         * @return array of strings
         */
@@ -1132,7 +1132,23 @@ abstract class Skin extends ContextSource {
        }
 
        /**
-        * 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
         */