Additional documentation updates and bump version to 3.0.42

2025-08-10 16:54:44 +02:00 · 2016-11-25 14:58:02 -05:00
parent 942cac2707
commit 35df716082
10 changed files with 254 additions and 93 deletions
--- a/wire/core/Field.php
+++ b/wire/core/Field.php
@@ -7,6 +7,8 @@
 * and is managed by the 'Fields' class.
 * 
 * #pw-summary Field represents a custom field that is used on a Page.
+ * #pw-var $field
+ * #pw-instantiate $field = $fields->get('field_name');
 * #pw-body Field objects are managed by the `$fields` API variable. 
 * #pw-use-constants
 * 
@@ -31,10 +33,10 @@
 * @property int|null $paginationLimit Used by paginated WireArray values to indicate limit to use during load. #pw-internal
 *
 * Common Inputfield properties that Field objects store:  
- * @property int|bool|null $required
- * @property string|null $requiredIf
- * @property string|null $showIf
- * @property int|null $columnWidth
+ * @property int|bool|null $required Whether or not this field is required during input #pw-group-properties
+ * @property string|null $requiredIf A selector-style string that defines the conditions under which input is required #pw-group-properties
+ * @property string|null $showIf A selector-style string that defines the conditions under which the Inputfield is shown #pw-group-properties
+ * @property int|null $columnWidth The Inputfield column width (percent) 10-100. #pw-group-properties
 * 
 * @method bool viewable(Page $page = null, User $user = null) Is the field viewable on the given $page by the given $user? #pw-group-access
 * @method bool editable(Page $page = null, User $user = null) Is the field editable on the given $page by the given $user? #pw-group-access
@@ -1003,6 +1005,8 @@ class Field extends WireData implements Saveable, Exportable {
 	/**
 	 * Set an override table name, or omit (or null) to restore default table name
 	 * 
+	 * #pw-group-advanced
+	 * 
 	 * @param null|string $table
 	 * 
 	 */
--- a/wire/core/HookEvent.php
+++ b/wire/core/HookEvent.php
@@ -9,6 +9,7 @@
 * Instances of HookEvent are passed to Hook handlers when their requested method has been called.
 * 
 * #pw-summary HookEvent is a type provided to hook functions with information about the event.
+ * #pw-var $event
 * #pw-body =
 * ~~~~~~
 * // Example
--- a/wire/core/Modules.php
+++ b/wire/core/Modules.php
@@ -14,6 +14,17 @@
 * https://processwire.com
 * 
 * #pw-summary Loads and manages all modules in ProcessWire. 
+ * #pw-body = 
+ * The `$modules` API variable is most commonly used for getting individual modules to use their API. 
+ * ~~~~~
+ * // Getting a module by name
+ * $m = $modules->get('MarkupPagerNav');
+ * 
+ * // Getting a module by name (alternate)
+ * $m = $modules->MarkupPagerNav;
+ * ~~~~~
+ * 
+ * #pw-body
 * 
 * @todo Move all module information methods to a ModulesInfo class
 * @todo Move all module loading methods to a ModulesLoad class
@@ -1156,7 +1167,7 @@ class Modules extends WireArray {
 	 * Get the requested Module (with options)
 	 * 
 	 * This is the same as `$modules->get()` except that you can specify additional options to modify default behavior.
-	 * These are the options you can speicfy in the `$options` array argument:
+	 * These are the options you can specify in the `$options` array argument:
 	 * 
 	 *  - `noPermissionCheck` (bool): Specify true to disable module permission checks (and resulting exception).
 	 *  - `noInstall` (bool): Specify true to prevent a non-installed module from installing from this request.
@@ -4717,6 +4728,8 @@ class Modules extends WireArray {
 	/**
 	 * Compile and return the given file for module, if allowed to do so
 	 * 
+	 * #pw-internal
+	 * 
 	 * @param Module|string $moduleName
 	 * @param string $file Optionally specify the module filename as an optimization
 	 * @param string|null $namespace Optionally specify namespace as an optimization
--- a/wire/core/ProcessWire.php
+++ b/wire/core/ProcessWire.php
@@ -45,7 +45,7 @@ class ProcessWire extends Wire {
 	 * Reversion revision number
 	 * 
 	 */
-	const versionRevision = 41;
+	const versionRevision = 42;

 	/**
 	 * Version suffix string (when applicable)
--- a/wire/core/WireCache.php
+++ b/wire/core/WireCache.php
@@ -375,6 +375,8 @@ class WireCache extends Wire {
 			$data = json_encode($data);
 			if($data === false) throw new WireException("Unable to encode array data for cache: $name"); 
 		}
+		
+		if(is_null($data)) $data = '';

 		$sql = 
 			'INSERT INTO caches (`name`, `data`, `expires`) VALUES(:name, :data, :expires) ' . 
--- a/wire/core/WireDatabaseBackup.php
+++ b/wire/core/WireDatabaseBackup.php
@@ -2,20 +2,18 @@

 /**
 * #pw-summary ProcessWire Database Backup and Restore
+ * #pw-summary-initialization It’s not typically necessary to call these initialization methods unless doing manual initialization.
+ * #pw-var $backup
+ * #pw-instantiate $backup = $database->backup();
+ * #pw-order-groups actions,reporting,initialization,advanced
 * #pw-body = 
 * This class intentionally does not have any external dependencies (other than PDO)
 * so that it can be included by outside tools for restoring/exporting, with the main
 * example of that being the ProcessWire installer. 
 * 
 * The recommended way to access these backup methods is via the `$database` API variable
- * method `$database->backups()`, which returns a `WireDatabaseBackup` instance.
- * 
- * ### Easy Initialization (recommended) 
- * ~~~~~
- * $backup = $database->backups();
- * ~~~~~
- * 
- * ### Manual Initialization (if you need it)
+ * method `$database->backups()`, which returns a `WireDatabaseBackup` instance, however
+ * you can also initialize the class manually if you prefer, like this:
 * ~~~~~
 * // determine where backups will go (should NOT be web accessible)
 * $backupPath = $config->paths->assets . 'backups/';
@@ -32,25 +30,21 @@
 * ~~~~~
 * ### Backup the database
 * ~~~~~
- * $options = array(); // optional
- * $file = $backup->backup($options);
+ * $file = $backup->backup();
 * if($file) {
- *   print_r($backup->notes());
+ *   echo "Backed up to: $file";
 * } else {
- *   print_r($backup->errors());
+ *   echo "Backup failed: " . implode("<br>", $backup->errors());
 * }
 * ~~~~~
- * Note: the `print_r()` function calls are just for demonstration and testing purposes. We are not suggesting
- * you actually do that except when testing.
 * 
 * ### Restore a database
 * ~~~~~
- * $options = array(); // optional
- * $success = $backup->restore($file, $options);
+ * $success = $backup->restore($file);
 * if($success) {
- *   print_r($backup->notes());
+ *   echo "Restored database from file: $file";
 * } else {
- *   print_r($backup->errors()); 
+ *   echo "Restore failed: " . implode("<br>", $backup->errors());
 * }
 * ~~~~~
 * #pw-body
@@ -269,7 +263,9 @@ class WireDatabaseBackup {
 	 * You should follow-up the construct call with one or both of the following:
 	 * 
 	 * 	- $backups->setDatabase(PDO|WireDatabasePDO);
-	 * 	- $backups->setDatabaseConfig(array|object); 
+	 * 	- $backups->setDatabaseConfig(array|object);
+	 * 
+	 * #pw-group-initialization
 	 * 
 	 * @param string $path Path where database files are stored
 	 * @throws \Exception
@@ -282,6 +278,8 @@ class WireDatabaseBackup {
 	/**
 	 * Set the current ProcessWire instance
 	 * 
+	 * #pw-internal
+	 * 
 	 * @param ProcessWire $wire
 	 * 
 	 */
@@ -292,8 +290,16 @@ class WireDatabaseBackup {
 	/**
 	 * Set the database configuration information
 	 * 
-	 * @param array|object $config Containing these properties: dbUser, dbHost, dbPort, dbName,
-	 * 	and optionally: dbPass, dbPath, dbCharset
+	 * #pw-group-initialization
+	 * 
+	 * @param array|Config|object $config Containing these properties: 
+	 *  - dbUser
+	 *  - dbHost
+	 *  - dbPort
+	 *  - dbName
+	 * 	- dbPass
+	 *  - dbPath (optional)
+	 *  - dbCharset (optional)
 	 * @return $this
 	 * @throws \Exception if missing required config settings
 	 * 
@@ -329,7 +335,9 @@ class WireDatabaseBackup {
 	}

 	/**
-	 * Set the database connection
+	 * Set the PDO database connection
+	 * 
+	 * #pw-group-initialization
 	 * 
 	 * @param \PDO|WireDatabasePDO $database
 	 * @throws \PDOException on invalid connection
@@ -346,6 +354,8 @@ class WireDatabaseBackup {
 	/**
 	 * Get current database connection, initiating the connection if not yet active
 	 * 
+	 * #pw-advanced
+	 * 
 	 * @return null|\PDO|WireDatabasePDO
 	 * @throws \Exception
 	 * 
@@ -377,6 +387,8 @@ class WireDatabaseBackup {
 	/**
 	 * Add an error and return last error
 	 * 
+	 * #pw-group-reporting
+	 * 
 	 * @param string $str If omitted, no error is added
 	 * @return string
 	 * 
@@ -389,6 +401,8 @@ class WireDatabaseBackup {
 	/**
 	 * Return all error messages that occurred
 	 * 
+	 * #pw-group-reporting
+	 * 
 	 * @param bool $reset Specify true to clear out existing errors or omit just to return error messages
 	 * @return array
 	 * 
@@ -401,6 +415,8 @@ class WireDatabaseBackup {
 	
 	/**
 	 * Record a note
+	 * 
+	 * #pw-group-reporting
 	 *
 	 * @param $key
 	 * @param $value
@@ -413,6 +429,8 @@ class WireDatabaseBackup {

 	/**
 	 * Get all notes
+	 * 
+	 * #pw-group-reporting
 	 *
 	 * @param bool $reset
 	 * @return array
@@ -427,6 +445,8 @@ class WireDatabaseBackup {
 	/**
 	 * Set path where database files are stored
 	 * 
+	 * #pw-group-initialization
+	 * 
 	 * @param string $path
 	 * @return $this
 	 * @throws \Exception if path has a problem
@@ -439,7 +459,15 @@ class WireDatabaseBackup {
 		$this->path = $path;
 		return $this;
 	}
-	
+
+	/**
+	 * Get path where database files are stored
+	 *
+	 * #pw-group-reporting
+	 *
+	 * @return string
+	 *
+	 */
 	public function getPath() {
 		return $this->path; 
 	}
@@ -448,6 +476,8 @@ class WireDatabaseBackup {
 	 * Return array of all backup files
 	 *
 	 * To get additional info on any of them, call getFileInfo($basename) method
+	 * 
+	 * #pw-group-reporting
 	 *
 	 * @return array of strings (basenames)
 	 *
@@ -467,8 +497,10 @@ class WireDatabaseBackup {
 	
 	/**
 	 * Get information about a backup file
+	 * 
+	 * #pw-group-reporting
 	 *
-	 * @param $filename
+	 * @param string $filename
 	 * @return array Returns associative array of information on success, empty array on failure
 	 *
 	 */
@@ -534,6 +566,8 @@ class WireDatabaseBackup {

 	/**
 	 * Get array of all table names
+	 * 
+	 * #pw-group-reporting
 	 *
 	 * @param bool $count If true, returns array will be indexed by name and include count of records as value
 	 * @param bool $cache Allow use of cache?
@@ -576,6 +610,8 @@ class WireDatabaseBackup {
 	/**
 	 * Perform a database export/dump
 	 * 
+	 * #pw-group-actions
+	 * 
 	 * @param array $options Options to modify default behavior:
 	 * - `filename` (string): filename for backup: default is to make a dated filename, but this can also be used (basename only, no path)
 	 * - `description` (string): optional description of this backup
@@ -640,7 +676,16 @@ class WireDatabaseBackup {
 	
 		return $success ? $file : false;
 	}
-	
+
+	/**
+	 * Set backup options
+	 * 
+	 * #pw-internal
+	 * 
+	 * @param array $options
+	 * @return $this
+	 * 
+	 */
 	public function setBackupOptions(array $options) {
 		$this->backupOptions = array_merge($this->backupOptions, $options); 
 		return $this;
@@ -869,7 +914,13 @@ class WireDatabaseBackup {
 	
 	
 	/**
-	 * Import a database SQL file that was created by this class
+	 * Restore/import a MySQL database dump file 
+	 * 
+	 * This method is designed to restore dump files created by the backup() method of this
+	 * class, however it *may* also work with dump files created from other sources like 
+	 * mysqldump or PhpMyAdmin.
+	 * 
+	 * #pw-group-actions
 	 * 
 	 * @param string $filename Filename to restore, optionally including path (if no path, then path set to construct is assumed)
 	 * @param array $options Options to modify default behavior: 
@@ -909,7 +960,16 @@ class WireDatabaseBackup {

 		return $success;
 	}
-	
+
+	/**
+	 * Set restore options
+	 * 
+	 * #pw-internal 
+	 * 
+	 * @param array $options
+	 * @return $this
+	 * 
+	 */
 	public function setRestoreOptions(array $options) {
 		$this->restoreOptions = array_merge($this->restoreOptions, $options);
 		return $this;
@@ -1049,6 +1109,8 @@ class WireDatabaseBackup {
 	 * 
 	 * This method assumes both files follow the SQL dump format created by this class. 
 	 * 
+	 * #pw-advanced
+	 * 
 	 * @param string $filename1 Original filename
 	 * @param string $filename2 Filename that may have statements that will update/override those in filename1
 	 * @param array $options
@@ -1143,6 +1205,8 @@ class WireDatabaseBackup {
 	/**
 	 * Returns array of all create table statements, indexed by table name
 	 * 
+	 * #pw-internal
+	 * 
 	 * @param string $filename to extract all CREATE TABLE statements from
 	 * @param array $options
 	 * @return bool|array of CREATE TABLE statements, associative: indexed by table name
@@ -1165,7 +1229,9 @@ class WireDatabaseBackup {
 	}

 	/**
-	 * Returns array of all INSERT statements, indexed by table name
+	 * Returns array of all INSERT statements in given filename, indexed by table name
+	 * 
+	 * #pw-internal
 	 *
 	 * @param string $filename to extract all CREATE TABLE statements from
 	 * @return array of arrays of INSERT statements. Base array is associative indexed by table name. 
--- a/wire/core/WireHttp.php
+++ b/wire/core/WireHttp.php
@@ -6,9 +6,11 @@
 * Provides capability for sending POST/GET requests to URLs
 * 
 * #pw-summary WireHttp enables you to send HTTP requests to URLs, download files, and more.
+ * #pw-var $http
+ * #pw-instantiate $http = new WireHttp();
 * #pw-body = 
 * ~~~~~
- * $http = new WireHttp();
+ * // Get the contents of a URL
 * $response = $http->get("http://domain.com/path/");
 * if($response !== false) {
 *   echo "Successful response: " . $sanitizer->entities($response);
@@ -899,7 +901,7 @@ class WireHttp extends Wire {
 	 *   - `content-type`: {content-type} (replaced with actual content type)
 	 *   - `content-transfer-encoding`: binary
 	 *   - `content-length`: {filesize} (replaced with actual filesize)
-	 *	 - To remove a header completely, make its value NULL and it won't be sent.
+	 *   - To remove a header completely, make its value NULL and it won't be sent.
 	 * @throws WireException
 	 *
 	 */
--- a/wire/core/WireInput.php
+++ b/wire/core/WireInput.php
@@ -586,7 +586,16 @@ class WireInput extends Wire {
 	}

 	/**
-	 * Return the current request method (i.e. GET, POST) or blank if not known
+	 * Return the current request method (i.e. GET, POST, etc.) or blank if not known
+	 * 
+	 * Possible return values are:
+	 * - GET
+	 * - POST
+	 * - HEAD
+	 * - PUT
+	 * - DELETE
+	 * - OPTIONS
+	 * - or blank if not known
 	 * 
 	 * @return string
 	 * @since 3.0.39
--- a/wire/core/WireMail.php
+++ b/wire/core/WireMail.php
@@ -1,37 +1,54 @@
 <?php namespace ProcessWire;

 /**
- * ProcessWire WireMail 
- *
+ * ProcessWire WireMail
+ * 
 * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
 * https://processwire.com
- *
- * USAGE:
- *
- * $mail = new WireMail(); 
 * 
- * // chained method call usage
- * $mail->to('user@domain.com')->from('you@company.com')->subject('Message Subject')->body('Message Body')->send();
+ * #pw-summary A module type that handles sending of email in ProcessWire
+ * #pw-var $m
+ * #pw-body = 
+ *
+ * Below are 3 different ways you can get a new instance of WireMail. 
+ * When possible we recommend using option A or B below.  
+ * ~~~~~
+ * $m = $mail->new(); // option A
+ * $m = wireMail(); // option B
+ * $m = new WireMail(); // option C
+ * ~~~~~
+ * Once you have an instance of WireMail (`$m`), you can use it to send email like in these examples below. 
+ * ~~~~~
+ * // chained (fluent) method call usage
+ * $m->to('user@domain.com')
+ *   ->from('you@company.com')
+ *   ->subject('Message Subject')
+ *   ->body('Message Body')
+ *   ->send();
 *
 * // separate method call usage
- * $mail->to('user@domain.com'); // specify CSV string or array for multiple addresses
- * $mail->from('you@company.com'); 
- * $mail->subject('Message Subject'); 
- * $mail->body('Message Body'); 
- * $mail->send();
+ * $m->to('user@domain.com'); // specify CSV string or array for multiple addresses
+ * $m->from('you@company.com'); 
+ * $m->subject('Message Subject'); 
+ * $m->body('Message Body'); 
+ * $m->send();
 *
- * // you can also set values without function calls:
- * $mail->to = 'user@domain.com';
- * $mail->from = 'you@company.com';
- * ...and so on.
+ * // optionally specify “from” or “to” names as 2nd argument 
+ * $m->to('user@domain.com', 'John Smith');
+ * $m->from('you@company.com', 'Mary Jane'); 
 *
 * // other methods or properties you might set (or get)
- * $mail->bodyHTML('<html><body><h1>Message Body</h1></body></html>'); 
- * $mail->header('X-Mailer', 'ProcessWire'); 
- * $mail->param('-f you@company.com'); // PHP mail() param (envelope from example)
+ * $m->bodyHTML('<html><body><h1>Message Body</h1></body></html>'); 
+ * $m->attachment('/path/to/file.ext'); 
+ * $m->fromName('Mary Jane');
+ * $m->toName('John Smith');
+ * $m->header('X-Mailer', 'ProcessWire'); 
+ * $m->param('-f you@company.com'); // PHP mail() param (envelope from example)
 *
 * // note that the send() function always returns the quantity of messages sent
- * $numSent = $mail->send();
+ * $numSent = $m->send();
+ * ~~~~~
+ * #pw-body
 * 
 * @method int send()
 * @property array $to
@@ -43,7 +60,7 @@
 * @property string $bodyHTML
 * @property array $header
 * @property array $param
- * @property array $attachments
+ * @property array $attachments Array of file attachments (if populated) #pw-advanced
 *
 */

@@ -70,7 +87,6 @@ class WireMail extends WireData implements WireMailInterface {
 		$this->mail['header']['X-Mailer'] = "ProcessWire/" . $this->className();
 	}

-
 	public function __get($key) {
 		if(array_key_exists($key, $this->mail)) return $this->mail[$key]; 
 		return parent::__get($key); 
@@ -146,11 +162,11 @@ class WireMail extends WireData implements WireMailInterface {
 	 * you specify NULL as the email address, in which case it clears them all.
 	 *
 	 * @param string|array|null $email Specify any ONE of the following: 
-	 *	1. Single email address or "User Name <user@example.com>" string.
-	 * 	2. CSV string of #1. 
-	 * 	3. Non-associative array of #1. 
-	 * 	4. Associative array of (email => name)
-	 *	5. NULL (default value, to clear out any previously set values)
+	 * - Single email address or "User Name <user@example.com>" string.
+	 * - CSV string of #1. 
+	 * - Non-associative array of #1. 
+	 * - Associative array of (email => name)
+	 * - NULL (default value, to clear out any previously set values)
 	 * @param string $name Optionally provide a TO name, applicable
 	 *	only when specifying #1 (single email) for the first argument. 
 	 * @return $this 
@@ -203,7 +219,7 @@ class WireMail extends WireData implements WireMailInterface {
 	 *
 	 * This sets the 'to name' for whatever the last added 'to' email address was.
 	 *
-	 * @param string 
+	 * @param string The 'to' name
 	 * @return $this 
 	 * @throws WireException if you attempt to set a toName before a to email. 
 	 *
@@ -238,7 +254,7 @@ class WireMail extends WireData implements WireMailInterface {
 	 * It is preferable to do this with the from() method, but this is provided to ensure that 
 	 * all properties can be set with direct access, i.e. $mailer->fromName = 'User Name';
 	 *
-	 * @param string 
+	 * @param string The 'from' name
 	 * @return $this 
 	 *
 	 */
@@ -250,7 +266,7 @@ class WireMail extends WireData implements WireMailInterface {
 	/**
 	 * Set the email subject
 	 *
-	 * @param string $subject 
+	 * @param string $subject Email subject text
 	 * @return $this 
 	 *
 	 */
@@ -261,8 +277,13 @@ class WireMail extends WireData implements WireMailInterface {

 	/**
 	 * Set the email message body (text only)
+	 * 
+	 * ~~~~~
+	 * $m = wireMail();
+	 * $m->body('Hello world');
+	 * ~~~~~
 	 *
-	 * @param string $body in text only
+	 * @param string $body Email body in text only
 	 * @return $this 
 	 *
 	 */
@@ -273,8 +294,15 @@ class WireMail extends WireData implements WireMailInterface {

 	/**
 	 * Set the email message body (HTML only)
+	 * 
+	 * This should be the text from an entire HTML document, not just an element.
+	 * 
+	 * ~~~~~
+	 * $m = wireMail();
+	 * $m->bodyHTML('<html><body><h1>Hello world</h1></body></html>');
+	 * ~~~~~
 	 *
-	 * @param string $body in HTML
+	 * @param string $body Email body in HTML
 	 * @return $this 
 	 *
 	 */
@@ -286,11 +314,13 @@ class WireMail extends WireData implements WireMailInterface {
 	/**
 	 * Set any email header
 	 *
-	 * Note: multiple calls will append existing headers. 
-	 * To remove an existing header, specify NULL as the value. 
+	 * - Multiple calls will append existing headers. 
+	 * - To remove an existing header, specify NULL as the value. 
+	 * 
+	 * #pw-advanced
 	 *
-	 * @param string $key
-	 * @param string $value
+	 * @param string $key Header name
+	 * @param string $value Header value
 	 * @return $this 
 	 *
 	 */
@@ -311,10 +341,15 @@ class WireMail extends WireData implements WireMailInterface {
 	/**
 	 * Set any email param 
 	 *
-	 * See $additional_parameters at: http://www.php.net/manual/en/function.mail.php
-	 * Note: multiple calls will append existing params. 
-	 * To remove an existing param, specify NULL as the value. 
-	 * This function may only be applicable to PHP mail().
+	 * See `$additional_parameters` at <http://www.php.net/manual/en/function.mail.php>
+	 * 
+	 * - Multiple calls will append existing params. 
+	 * - To remove an existing param, specify NULL as the value. 
+	 * 
+	 * This function may only be applicable if you don't have other WireMail modules
+	 * installed as email params are only used by PHP's `mail()` function. 
+	 * 
+	 * #pw-advanced
 	 *
 	 * @param string $value
 	 * @return $this 
@@ -333,17 +368,19 @@ class WireMail extends WireData implements WireMailInterface {
 	 * Add a file to be attached to the email
 	 * 
 	 * ~~~~~~
-	 * $mail = new WireMail();
-	 * $mail->to('user@domain.com')->from('hello@world.com');
-	 * $mail->subject('Test attachment');
-	 * $mail->body('This is just a test of a file attachment');
-	 * $mail->attachment('/path/to/file.jpg'); 
-	 * $mail->send();
+	 * $m = wireMail();
+	 * $m->to('user@domain.com')->from('hello@world.com');
+	 * $m->subject('Test attachment');
+	 * $m->body('This is just a test of a file attachment');
+	 * $m->attachment('/path/to/file.jpg'); 
+	 * $m->send();
 	 * ~~~~~~
+	 * 
+	 * #pw-advanced
 	 *
-	 * Multiple calls will append attachments. 
-	 * To remove the supplied attachments, specify NULL as the value. 
-	 * This function may not be supported by 3rd party WireMail modules. 
+	 * - Multiple calls will append attachments. 
+	 * - To remove the supplied attachments, specify NULL as the value. 
+	 * - Attachments may or may not be supported by 3rd party WireMail modules. 
 	 *
 	 * @param string $value Full path and filename of file attachment
 	 * @param string $filename Optional different basename for file as it appears in the mail
@@ -363,7 +400,9 @@ class WireMail extends WireData implements WireMailInterface {
 	/**
 	 * Send the email
 	 *
-	 * This is the primary method that modules extending this class would want to replace.
+	 * Call this method only after you have specified at least the `subject`, `to` and `body`.
+	 * 
+	 * #pw-notes This is the primary method that modules extending this class would want to replace.
 	 *
 	 * @return int Returns a positive number (indicating number of addresses emailed) or 0 on failure. 
 	 *
@@ -462,7 +501,9 @@ class WireMail extends WireData implements WireMailInterface {
 	}
 	
 	/**
-	 * Encode the subject, use mbstring if available
+	 * Encode a subject, use mbstring if available
+	 * 
+	 * #pw-advanced
 	 *
 	 * @param string $subject
 	 * @return string
@@ -531,6 +572,8 @@ class WireMail extends WireData implements WireMailInterface {
 	 *
 	 * Uses short notation for charset and encoding suitable for email headers
 	 * as laid out in rfc2047.
+	 * 
+	 * #pw-advanced
 	 *
 	 * @param string $text
 	 * @return string
--- a/wire/core/WireMailTools.php
+++ b/wire/core/WireMailTools.php
@@ -7,6 +7,21 @@
 * https://processwire.com
 * 
 * #pw-summary Provides an API interface to email and WireMail. 
+ * #pw-body = 
+ * ~~~~~
+ * // Simple usage example
+ * $message = $mail->new();
+ * $message->subject('Hello world')
+ *   ->to('user@domain.com')
+ *   ->from('you@company.com');
+ *   ->body('Hello there big world')
+ *   ->bodyHTML('<h2>Hello there big world</h2>');
+ * $numSent = $message->send();
+ * ~~~~~
+ * #pw-body
+ * 
+ * @method WireMail new() Create a new WireMail() instance
+ * @property WireMail new Get a new WireMail() instance (same as method version)
 *
 *
 */
@@ -17,10 +32,10 @@ class WireMailTools extends Wire {
 	 * Get a new WireMail instance for sending email
 	 * 
 	 * ~~~~~
-	 * $mailer = $mail->new();
-	 * $mailer->to('user@domain.com')->from('you@company.com');
-	 * $mailer->subject('Mail Subject')->body('Mail Body Text')->bodyHTML('Body HTML');
-	 * $numSent = $mailer->send();
+	 * $message = $mail->new();
+	 * $message->to('user@domain.com')->from('you@company.com');
+	 * $message->subject('Mail Subject')->body('Mail Body Text')->bodyHTML('Body HTML');
+	 * $numSent = $message->send();
 	 * ~~~~~
 	 *
 	 * @return WireMail
@@ -41,6 +56,7 @@ class WireMailTools extends Wire {
 		}
 		// if no module found, default to WireMail
 		if(is_null($mail)) $mail = $this->wire(new WireMail());
+		/** @var WireMail $mail */

 		// reset just in case module was not singular
 		$mail->to();
@@ -138,4 +154,9 @@ class WireMailTools extends Wire {
 		return $numSent;
 	}

+	public function __get($key) {
+		if($key === 'new') return $this->new();
+		return parent::__get($key);
+	}
+
 }