From 368ce258641a4e8fae6b2e49c89f173d7e3ada69 Mon Sep 17 00:00:00 2001
From: Andreas Gohr <andi@splitbrain.org>
Date: Fri, 19 May 2017 21:12:37 +0200
Subject: [PATCH] more doc blocks for the menu system
---
inc/Menu/AbstractMenu.php | 7 +++++++
inc/Menu/DetailMenu.php | 6 ++++++
inc/Menu/Item/AbstractItem.php | 37 +++++++++++++++++++++++++---------
inc/Menu/Item/Admin.php | 5 +++++
inc/Menu/Item/Back.php | 6 ++++++
inc/Menu/Item/Backlink.php | 5 +++++
inc/Menu/Item/Edit.php | 6 ++++++
inc/Menu/Item/ImgBackto.php | 5 +++++
inc/Menu/Item/Index.php | 9 +++++++--
inc/Menu/Item/Login.php | 5 +++++
inc/Menu/Item/Media.php | 5 +++++
inc/Menu/Item/MediaManager.php | 6 +++++-
inc/Menu/Item/Profile.php | 5 +++++
inc/Menu/Item/Recent.php | 5 +++++
inc/Menu/Item/Register.php | 5 +++++
inc/Menu/Item/Resendpwd.php | 5 +++++
inc/Menu/Item/Revert.php | 5 +++++
inc/Menu/Item/Revisions.php | 5 +++++
inc/Menu/Item/Subscribe.php | 5 +++++
inc/Menu/Item/Top.php | 6 ++++++
inc/Menu/MobileMenu.php | 7 +++++++
inc/Menu/PageMenu.php | 5 +++++
inc/Menu/SiteMenu.php | 5 +++++
inc/Menu/UserMenu.php | 5 +++++
24 files changed, 153 insertions(+), 12 deletions(-)
diff --git a/inc/Menu/AbstractMenu.php b/inc/Menu/AbstractMenu.php
index 8c01abe08..ed4113b70 100644
--- a/inc/Menu/AbstractMenu.php
+++ b/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 */
diff --git a/inc/Menu/DetailMenu.php b/inc/Menu/DetailMenu.php
index f9a46008e..27c0c6fce 100644
--- a/inc/Menu/DetailMenu.php
+++ b/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';
diff --git a/inc/Menu/Item/AbstractItem.php b/inc/Menu/Item/AbstractItem.php
index 1893a3796..4eac2c114 100644
--- a/inc/Menu/Item/AbstractItem.php
+++ b/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;
diff --git a/inc/Menu/Item/Admin.php b/inc/Menu/Item/Admin.php
index a5c4c0c0e..197f2c6da 100644
--- a/inc/Menu/Item/Admin.php
+++ b/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';
diff --git a/inc/Menu/Item/Back.php b/inc/Menu/Item/Back.php
index 708bdc587..407bbe2fb 100644
--- a/inc/Menu/Item/Back.php
+++ b/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 */
diff --git a/inc/Menu/Item/Backlink.php b/inc/Menu/Item/Backlink.php
index 3a39426fc..996bcb20b 100644
--- a/inc/Menu/Item/Backlink.php
+++ b/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';
diff --git a/inc/Menu/Item/Edit.php b/inc/Menu/Item/Edit.php
index ea883b463..05467674d 100644
--- a/inc/Menu/Item/Edit.php
+++ b/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 */
diff --git a/inc/Menu/Item/ImgBackto.php b/inc/Menu/Item/ImgBackto.php
index 0d5f726f2..72820a53a 100644
--- a/inc/Menu/Item/ImgBackto.php
+++ b/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 */
diff --git a/inc/Menu/Item/Index.php b/inc/Menu/Item/Index.php
index f762c18ae..5ae35b23f 100644
--- a/inc/Menu/Item/Index.php
+++ b/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;
}
diff --git a/inc/Menu/Item/Login.php b/inc/Menu/Item/Login.php
index 758473052..d2b3ccd47 100644
--- a/inc/Menu/Item/Login.php
+++ b/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';
diff --git a/inc/Menu/Item/Media.php b/inc/Menu/Item/Media.php
index b06334807..b2d7667a3 100644
--- a/inc/Menu/Item/Media.php
+++ b/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';
diff --git a/inc/Menu/Item/MediaManager.php b/inc/Menu/Item/MediaManager.php
index 49abb5426..146b56f7c 100644
--- a/inc/Menu/Item/MediaManager.php
+++ b/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) {
diff --git a/inc/Menu/Item/Profile.php b/inc/Menu/Item/Profile.php
index b993e0db6..237d10a2e 100644
--- a/inc/Menu/Item/Profile.php
+++ b/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';
diff --git a/inc/Menu/Item/Recent.php b/inc/Menu/Item/Recent.php
index e08d63530..ff90ce605 100644
--- a/inc/Menu/Item/Recent.php
+++ b/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 */
diff --git a/inc/Menu/Item/Register.php b/inc/Menu/Item/Register.php
index 6f58c7ba6..3dbe9e24a 100644
--- a/inc/Menu/Item/Register.php
+++ b/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 */
diff --git a/inc/Menu/Item/Resendpwd.php b/inc/Menu/Item/Resendpwd.php
index 6bc0c1016..ffa99d8f8 100644
--- a/inc/Menu/Item/Resendpwd.php
+++ b/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 */
diff --git a/inc/Menu/Item/Revert.php b/inc/Menu/Item/Revert.php
index 83072e469..a360c6842 100644
--- a/inc/Menu/Item/Revert.php
+++ b/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 */
diff --git a/inc/Menu/Item/Revisions.php b/inc/Menu/Item/Revisions.php
index 63b0b94a5..3452a9bd0 100644
--- a/inc/Menu/Item/Revisions.php
+++ b/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 */
diff --git a/inc/Menu/Item/Subscribe.php b/inc/Menu/Item/Subscribe.php
index f71414ade..617bacca9 100644
--- a/inc/Menu/Item/Subscribe.php
+++ b/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';
diff --git a/inc/Menu/Item/Top.php b/inc/Menu/Item/Top.php
index 6c5307e45..78181d0d5 100644
--- a/inc/Menu/Item/Top.php
+++ b/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';
diff --git a/inc/Menu/MobileMenu.php b/inc/Menu/MobileMenu.php
index 58ce1964e..6fe98b35c 100644
--- a/inc/Menu/MobileMenu.php
+++ b/inc/Menu/MobileMenu.php
@@ -4,6 +4,13 @@ namespace dokuwiki\Menu;
use dokuwiki\Menu\Item\AbstractItem;
+/**
+ * Class MobileMenu
+ *
+ * Note: this does not inherit from AbstractMenu because it is not working like the other
+ * menus. This is a meta menu, aggregating the items from the other menus and offering a combined
+ * view. The idea is to use this on mobile devices, thus the context is fixed to CTX_MOBILE
+ */
class MobileMenu {
/**
diff --git a/inc/Menu/PageMenu.php b/inc/Menu/PageMenu.php
index 4db02b6ad..9c0a55e2d 100644
--- a/inc/Menu/PageMenu.php
+++ b/inc/Menu/PageMenu.php
@@ -2,6 +2,11 @@
namespace dokuwiki\Menu;
+/**
+ * Class PageMenu
+ *
+ * Actions manipulating the current page. Shown as a floating menu in the dokuwiki template
+ */
class PageMenu extends AbstractMenu {
protected $view = 'page';
diff --git a/inc/Menu/SiteMenu.php b/inc/Menu/SiteMenu.php
index 27d077ea0..dba6888c7 100644
--- a/inc/Menu/SiteMenu.php
+++ b/inc/Menu/SiteMenu.php
@@ -2,6 +2,11 @@
namespace dokuwiki\Menu;
+/**
+ * Class SiteMenu
+ *
+ * Actions that are not bound to an individual page but provide toolsfor the whole wiki.
+ */
class SiteMenu extends AbstractMenu {
protected $view = 'site';
diff --git a/inc/Menu/UserMenu.php b/inc/Menu/UserMenu.php
index 99cc7bd9a..01028d3cc 100644
--- a/inc/Menu/UserMenu.php
+++ b/inc/Menu/UserMenu.php
@@ -2,6 +2,11 @@
namespace dokuwiki\Menu;
+/**
+ * Class UserMenu
+ *
+ * Actions related to the current user
+ */
class UserMenu extends AbstractMenu {
protected $view = 'user';
--
GitLab