more doc blocks for the menu system

inc/Menu/AbstractMenu.php

@@ -4,6 +4,13 @@ namespace dokuwiki\Menu;
 
 use dokuwiki\Menu\Item\AbstractItem;
 
+/**
+ * Class AbstractMenu
+ *
+ * Basic menu functionality. A menu defines a list of AbstractItem that shall be shown.
+ * It contains convenience functions to display the menu in HTML, but template authors can also
+ * just accesst the items via getItems() and create the HTML as however they see fit.
+ */
 abstract class AbstractMenu {
 
     /** @var string[] list of Item classes to load */

inc/Menu/DetailMenu.php

@@ -2,6 +2,12 @@
 
 namespace dokuwiki\Menu;
 
+/**
+ * Class DetailMenu
+ *
+ * This menu offers options on an image detail view. It usually displayed similar to
+ * the PageMenu.
+ */
 class DetailMenu extends AbstractMenu {
 
     protected $view = 'detail';

inc/Menu/Item/AbstractItem.php

@@ -26,17 +26,36 @@ abstract class AbstractItem {
     /** menu item is to be shown in all contexts */
     const CTX_ALL = 3;
 
-    protected $type        = '';
-    protected $accesskey   = '';
-    protected $id          = '';
-    protected $method      = 'get';
-    protected $params      = array();
-    protected $nofollow    = true;
+    /** @var string name of the action, usually the lowercase class name */
+    protected $type = '';
+    /** @var string optional keyboard shortcut */
+    protected $accesskey = '';
+    /** @var string the page id this action links to */
+    protected $id = '';
+    /** @var string the method to be used when this action is used in a form */
+    protected $method = 'get';
+    /** @var array parameters for the action (should contain the do parameter) */
+    protected $params = array();
+    /** @var bool when true, a rel=nofollow should be used */
+    protected $nofollow = true;
+    /** @var string this item's label may contain a placeholder, which is replaced with this */
     protected $replacement = '';
-    protected $svg         = DOKU_INC . 'lib/images/menu/00-default_checkbox-blank-circle-outline.svg';
-    protected $label       = '';
-    protected $context     = self::CTX_ALL;
+    /** @var string the full path to the SVG icon of this menu item */
+    protected $svg = DOKU_INC . 'lib/images/menu/00-default_checkbox-blank-circle-outline.svg';
+    /** @var string can be set to overwrite the default lookup in $lang.btn_* */
+    protected $label = '';
+    /** @var int the context this titme is shown in */
+    protected $context = self::CTX_ALL;
 
+    /**
+     * AbstractItem constructor.
+     *
+     * Sets the dynamic properties
+     *
+     * Children should always call the parent constructor!
+     *
+     * @throws \RuntimeException when the action is disabled
+     */
     public function __construct() {
         global $ID;
         $this->id = $ID;

inc/Menu/Item/Admin.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Admin
+ *
+ * Opens the Admin screen. Only shown to managers or above
+ */
 class Admin extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/settings.svg';

inc/Menu/Item/Back.php

@@ -2,6 +2,12 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Back
+ *
+ * @fixme where is this used?
+ * @fixme missing SVG
+ */
 class Back extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Backlink.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Backlink
+ *
+ * Shows the backlinks for the current page
+ */
 class Backlink extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/08-backlink_link-variant.svg';

inc/Menu/Item/Edit.php

@@ -2,6 +2,12 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Edit
+ *
+ * Most complex item. Shows the edit button but mutates to show, draft and create based on
+ * current state.
+ */
 class Edit extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/ImgBackto.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class ImgBackto
+ *
+ * Links back to the originating page from a detail image view
+ */
 class ImgBackto extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Index.php

@@ -2,19 +2,24 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Index
+ *
+ * Shows the sitemap
+ */
 class Index extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/file-tree.svg';
 
     /** @inheritdoc */
     public function __construct() {
+        global $conf;
+        global $ID;
         parent::__construct();
 
         $this->accesskey = 'x';
 
         // allow searchbots to get to the sitemap from the homepage (when dokuwiki isn't providing a sitemap.xml)
-        global $conf;
-        global $ID;
         if($conf['start'] == $ID && !$conf['sitemap']) {
             $this->nofollow = false;
         }

inc/Menu/Item/Login.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Login
+ *
+ * Show a login or logout item, based on the current state
+ */
 class Login extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/login.svg';

inc/Menu/Item/Media.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Media
+ *
+ * Opens the media manager
+ */
 class Media extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/folder-multiple-image.svg';

inc/Menu/Item/MediaManager.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class MediaManager
+ *
+ * Opens the current image in the media manager. Used on image detail view.
+ */
 class MediaManager extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/11-mediamanager_folder-image.svg';
@@ -11,7 +16,6 @@ class MediaManager extends AbstractItem {
         global $IMG;
         parent::__construct();
 
-        // View image in media manager
         $imgNS = getNS($IMG);
         $authNS = auth_quickaclcheck("$imgNS:*");
         if($authNS < AUTH_UPLOAD) {

inc/Menu/Item/Profile.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Profile
+ *
+ * Open the user's profile
+ */
 class Profile extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/account-card-details.svg';

inc/Menu/Item/Recent.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Recent
+ *
+ * Show the site wide recent changes
+ */
 class Recent extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Register.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Register
+ *
+ * Open the view to register a new account
+ */
 class Register extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Resendpwd.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Resendpwd
+ *
+ * Access the "forgot password" dialog
+ */
 class Resendpwd extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Revert.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Revert
+ *
+ * Quick revert to the currently shown page revision
+ */
 class Revert extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Revisions.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Revisions
+ *
+ * Access the old revisions of the current page
+ */
 class Revisions extends AbstractItem {
 
     /** @inheritdoc */

inc/Menu/Item/Subscribe.php

@@ -2,6 +2,11 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Subscribe
+ *
+ * Access the subscription management view
+ */
 class Subscribe extends AbstractItem {
 
     protected $svg = DOKU_INC . 'lib/images/menu/09-subscribe_email-outline.svg';

inc/Menu/Item/Top.php

@@ -2,6 +2,12 @@
 
 namespace dokuwiki\Menu\Item;
 
+/**
+ * Class Top
+ *
+ * Scroll back to the top. Uses a hash as $id which is handled special in getLink().
+ * Not shown in mobile context
+ */
 class Top extends AbstractItem {
 
     protected $svg       = DOKU_INC . 'lib/images/menu/10-top_arrow-up.svg';