[DOCUMENTATION][DEVELOPERS][PLUGINS] Some updates to Plugins doc

DOCUMENTATION/DEVELOPERS/Plugins/README.md

@@ -1,8 +1,8 @@
 Plugin Development
-=======================
+==================
 
 SamplePlugin.php
------------------------
+----------------
 
 Each plugin requires a main class to interact with the GNU social system.
 
@@ -15,7 +15,7 @@ have pre-defined arguments, based on which event they're handling. A typical
 event handler:
 
 ```php
-function onSomeEvent($paramA, &$paramB)
+public function onSomeEvent($paramA, &$paramB): bool
 {
     if ($paramA == 'jed') {
         throw new Exception(sprintf(_m("Invalid parameter %s"), $paramA));
@@ -26,7 +26,7 @@ function onSomeEvent($paramA, &$paramB)
 ```
 
 Event Handlers
------------------------
+--------------
 
 Event handlers must return a Boolean value.
 
@@ -41,50 +41,43 @@ If the handler throws an exception, processing will stop, and the exception's
 error will be shown to the user.
 
 Installation
-------------------
+------------
 
-To install a plugin (like this one), site admins add the following code to their
+To enable a plugin (like the SamplePlugin), site admins add the following code to their
 config.php file:
 
 ```php
 addPlugin('Sample');
 ```
 
-Plugins must be installed in one of the following directories:
-
-* local/plugins/{$pluginclass}.php
-* local/plugins/{$name}/{$pluginclass}.php
-* local/{$pluginclass}.php
-* local/{$name}/{$pluginclass}.php
-* plugins/{$pluginclass}.php
-* plugins/{$name}/{$pluginclass}.php
+Third Party Plugins must be installed in `local/plugins/{$name}/{$pluginclass}.php`
 
 Here, `{$name}` is the name of the plugin, like 'Sample', and `{$pluginclass}`
 is the name of the main class, like 'SamplePlugin'. Plugins that are part of
 the main GNU social distribution go in 'plugins' and third-party or local ones
 go in 'local'.
 
-Simple plugins can be implemented as a single module. Others are more complex
-and require additional modules; these should use their own directory, like
+Simple plugins can be implemented as a single plugin. Others are more complex
+and require additional plugins; these should use their own directory, like
 'local/plugins/{$name}/'. All files related to the plugin, including images,
-JavaScript, CSS, external libraries or PHP modules should go in the plugin
+JavaScript, CSS, external libraries or PHP plugins should go in the plugin
 directory.
 
 Plugin Configuration
-------------------
+--------------------
 
 Plugins are configured using public instance attributes. To set their values,
 site administrators use this syntax:
 
 ```php
-addPlugin('Sample', ('attr1' => 'foo', 'attr2' => 'bar'));
+addPlugin('Sample', ['attr1' => 'foo', 'attr2' => 'bar']);
 ```
 
 The same plugin class can be initialized multiple times with different arguments:
 
 ```php
-addPlugin('EmailNotify', array('sendTo' => 'evan@status.net'));
-addPlugin('EmailNotify', array('sendTo' => 'brionv@status.net'));
+addPlugin('EmailNotify', ['sendTo' => 'evan@status.net']);
+addPlugin('EmailNotify', ['sendTo' => 'brionv@status.net']);
 ```
 
 ```php
@@ -96,34 +89,34 @@ class SamplePlugin extends Plugin
 ```
 
 Initialization
-------------------
+--------------
 
 Plugins overload this method to do any initialization they need, like connecting
-to remote servers or creating paths or so on. @return boolean hook value; true
+to remote servers or creating paths or so on. @return bool hook value; true
 means continue processing, false means stop.
 
 ```php
-function initialize()
+public function initialize(): bool
 {
     return true;
 }
 ```
 
 Clean Up
-------------------
+--------
 
 Plugins overload this method to do any cleanup they need, like disconnecting from
 remote servers or deleting temp files or so on.
 
 ```php
-function cleanup()
+public function cleanup(): bool
 {
     return true;
 }
 ```
 
 Database schema setup
-------------------
+---------------------
 
 Plugins can add their own tables to the GNU social database. Plugins should use
 GNU social's schema interface to add or delete tables. The ensureTable() method
@@ -135,25 +128,26 @@ the checkschema.php script is run, greatly improving performance. However, they
 need to remember to run that script after installing or upgrading a plugin!
 
 ```php
-function onCheckSchema()
+public function onCheckSchema(): bool
 {
     $schema = Schema::get();
 
     // '''For storing user-submitted flags on profiles'''
 
-    $schema->ensureTable('user_greeting_count',
-                          array(new ColumnDef('user_id', 'integer', null,
-                                              true, 'PRI'),
-                                new ColumnDef('greeting_count', 'integer')));
+    $schema->ensureTable('user_greeting_count',[
+            new ColumnDef('user_id', 'integer', null, true, 'PRI'),
+            new ColumnDef('greeting_count', 'integer')
+        ]
+    );
 
     return true;
 }
 ```
 
-Load related modules when needed
-------------------
+Load related plugins when needed
+--------------------------------
 
-Most non-trivial plugins will require extra modules to do their work. Typically
+Most non-trivial plugins will require extra plugins to do their work. Typically
 these include data classes, action classes, widget classes, or external libraries.
 
 This method receives a class name and loads the PHP file related to that class.
@@ -166,26 +160,26 @@ in this plugin! So, make sure to return true by default to let other plugins,
 and the core code, get a chance.
 
 ```php
-function onAutoload($cls)
+public function onAutoload($cls): bool
 {
-    $dir = dirname(__FILE__);
+    $dir = __DIR__;
 
     switch ($cls)
     {
-    case 'HelloAction':
-        include_once $dir . '/' . strtolower(mb_substr($cls, 0, -6)) . '.php';
-        return false;
-    case 'User_greeting_count':
-        include_once $dir . '/'.$cls.'.php';
-        return false;
-    default:
-        return true;
+        case 'HelloAction':
+            include_once $dir . '/' . strtolower(mb_substr($cls, 0, -6)) . '.php';
+            return false;
+        case 'User_greeting_count':
+            include_once $dir . '/'.$cls.'.php';
+            return false;
+        default:
+            return true;
     }
 }
 ```
 
 Map URLs to actions
-------------------
+-------------------
 
 This event handler lets the plugin map URLs on the site to actions (and thus an
 action handler class). Note that the action handler class for an action will be
@@ -193,28 +187,28 @@ named 'FoobarAction', where action = 'foobar'. The class must be loaded in the
 onAutoload() method.
 
 ```php
-function onRouterInitialized($m)
+public function onRouterInitialized($m): bool
 {
     $m->connect('main/hello',
-                array('action' => 'hello'));
+                ['action' => 'hello']);
     return true;
 }
 ```
 
 Modify the default menu to link to our custom action
-------------------
+-----------------------------------------------------
 
 Using event handlers, it's possible to modify the default UI for pages almost
 without limit. In this method, we add a menu item to the default primary menu
 for the interface to link to our action.
 
 Action Class
-------------------
+------------
 
 The Action class provides a rich set of events to hook, as well as output methods.
 
 ```php
-function onEndPrimaryNav($action)
+public function onEndPrimaryNav($action): bool
 {
     // '''common_local_url()''' gets the correct URL for the action name we provide
 
@@ -225,18 +219,20 @@ function onEndPrimaryNav($action)
 
 public function onPluginVersion(&$versions): bool
 {
-    $versions[] = array('name' => 'Sample',
-                        'version' => GNUSOCIAL_VERSION,
-                        'author' => 'Brion Vibber, Evan Prodromou',
-                        'homepage' => 'http://example.org/plugin',
-                        'rawdescription' =>
-                        _m('A sample plugin to show basics of development for new hackers.'));
+    $versions[] = [
+        'name' => 'Sample',
+        'version' => GNUSOCIAL_VERSION,
+        'author' => 'Brion Vibber, Evan Prodromou',
+        'homepage' => 'http://example.org/plugin',
+        'rawdescription' =>
+        _m('A sample plugin to show basics of development for new hackers.')
+    ];
     return true;
 }
 ```
 
 hello.php
-------------------
+---------
 
 This section is taken directly from the 'hello.php'. ( plugins/Sample/hello.php )
 
@@ -255,7 +251,7 @@ class HelloAction extends Action
 ```
 
 Take arguments for running
-------------------
+--------------------------
 
 This method is called first, and it lets the action class get all its arguments
 and validate them. It's also the time to fetch any relevant data from the database.
@@ -263,8 +259,8 @@ and validate them. It's also the time to fetch any relevant data from the databa
 Action classes should run parent::prepare(array $args = []) as the first line
 of this method to make sure the default argument-processing happens.
 
-```php     
-function prepare(array $args = [])
+```php
+public function prepare(array $args = []): bool
 {
     parent::prepare($args);
 
@@ -279,14 +275,14 @@ function prepare(array $args = [])
 ```
 
 Handle request
-------------------
+--------------
 
 This is the main method for handling a request. Note that most preparation
 should be done in the prepare() method; by the time handle() is called the
 action should be more or less ready to go.
 
 ```php
-function handle()
+public function handle(): void
 {
     parent::handle();
 
@@ -300,7 +296,7 @@ Title of this page
 Override this method to show a custom title.
 
 ```php
-function title()
+public function title(): string
 {
     if (empty($this->user)) {
         return _m('Hello');
@@ -311,7 +307,7 @@ function title()
 ```
 
 Show content in the content area
-------------------
+--------------------------------
 
 The default GNU social page has a lot of decorations: menus, logos, tabs, all
 that jazz. This method is used to show content in the content area of the
@@ -319,15 +315,15 @@ page; it's the main thing you want to overload. This method also demonstrates
 use of a plural localized string.
 
 ```php
-function showContent()
+public function showContent(): void
 {
     if (empty($this->user)) {
-        $this->element('p', array('class' => 'greeting'),
+        $this->element('p', ['class' => 'greeting'],
                        _m('Hello, stranger!'));
     } else {
-        $this->element('p', array('class' => 'greeting'),
+        $this->element('p', ['class' => 'greeting'],
                        sprintf(_m('Hello, %s'), $this->user->nickname));
-        $this->element('p', array('class' => 'greeting_count'),
+        $this->element('p', ['class' => 'greeting_count'],
                        sprintf(_m('I have greeted you %d time.',
                                   'I have greeted you %d times.',
                                   $this->gc->greeting_count),
@@ -337,7 +333,7 @@ function showContent()
 ```
 
 Return true if read only.
-------------------
+-------------------------
 
 Some actions only read from the database; others read and write. The simple
 database load-balancer built into GNU social will direct read-only actions to
@@ -347,9 +343,8 @@ This defaults to false to avoid data integrity issues, but you should make sure
 to overload it for performance gains.
 
 ```php
-function isReadOnly($args)
+public function isReadOnly($args): bool
 {
     return false;
 }
 ```
-

DOCUMENTATION/DEVELOPERS/Plugins/Sample Plugins/Awesomeness/includes/AwesomenessPlugin.php

@@ -13,39 +13,13 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with GNU social.  If not, see <http://www.gnu.org/licenses/>.
-/**
- * StatusNet, the distributed open-source microblogging tool
- *
- * Module to add additional awesomenss to StatusNet
- *
- * PHP version 5
- *
- * LICENCE: This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @category  Module
- * @package   StatusNet
- * @author    Jeroen De Dauw <jeroendedauw@gmail.com>
- * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
- * @link      http://status.net/
- */
 
 defined('GNUSOCIAL') || die();
 
 /**
  * Fun sample plugin: tweaks input data and adds a 'Cornify' widget to sidebar.
  *
- * @category Module
+ * @category Plugin
  * @package  GNUsocial
  * @author   Jeroen De Dauw <jeroendedauw@gmail.com>
  * @copyright 2019 Free Software Foundation, Inc http://www.fsf.org
@@ -63,7 +37,7 @@ class AwesomenessPlugin extends Plugin
             'version' => self::PLUGIN_VERSION,
             'author' => 'Jeroen De Dauw',
             'homepage' => 'https://git.gnu.io/gnu/gnu-social/tree/master/plugins/Awesomeness',
-            // TRANS: Module description for a sample plugin.
+            // TRANS: Plugin description for a sample plugin.
             'rawdescription' => _m('The Awesomeness plugin adds additional awesomeness ' .
                 'to a GNU social installation.')
         ];
@@ -80,7 +54,7 @@ class AwesomenessPlugin extends Plugin
     public function onEndShowSections(Action $action)
     {
         $action->elementStart('div', ['id'    => 'cornify_section',
-            'class' => 'section']);
+                                      'class' => 'section']);
 
         $action->raw(
             <<<EOT