Phpdoc improvements to various core classes

wire/core/Fieldgroup.php

@@ -18,6 +18,8 @@
  * 
  * @property int $id Fieldgroup database ID #pw-group-retrieval
  * @property string $name Fieldgroup name #pw-group-retrieval
+ * @property array $fields_id Array of all field IDs in this Fieldgroup
+ * @property null|FieldsArray $removedFields Null when there are no removed fields, or FieldsArray when there are. 
  *
  */
 class Fieldgroup extends WireArray implements Saveable, Exportable, HasLookupItems {
@@ -335,7 +337,7 @@ class Fieldgroup extends WireArray implements Saveable, Exportable, HasLookupIte
 	 * #pw-group-retrieval
 	 *
 	 * @param string|int $key Property name to retrieve, or Field name
-	 * @return Field|string|int|null
+	 * @return Field|string|int|null|array
 	 *
 	 */
 	public function get($key) {

wire/core/Fieldgroups.php

@@ -3,7 +3,9 @@
 /**
  * ProcessWire Fieldgroups
  *
- * Maintains collections of Fieldgroup instances. 
+ * #pw-summary Maintains collections of Fieldgroup object instances and represents the `$fieldgroups` API variable.
+ * #pw-body For full details on all methods available in a Fieldgroup, be sure to also see the `WireArray` class.
+ * #pw-var $fieldgroups
  * 
  * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
  * https://processwire.com
@@ -466,13 +468,13 @@ class Fieldgroups extends WireSaveableItemsLookup {
 
 		if(($field->flags & Field::flagGlobal) && (!$template || !$template->noGlobal)) {
 			return
-				"Field '$field' may not be removed from fieldgroup '{$this->name}' " . 
+				"Field '$field' may not be removed from fieldgroup '$fieldgroup->name' " . 
 				"because it is globally required (Field::flagGlobal).";
 		}
 
 		if($field->flags & Field::flagPermanent) {
 			return 
-				"Field '$field' may not be removed from fieldgroup '{$this->name}' " . 
+				"Field '$field' may not be removed from fieldgroup '$fieldgroup->name' " . 
 				"because it is permanent (Field::flagPermanent).";
 		}
 

wire/core/Fields.php

@@ -8,7 +8,16 @@
  * ProcessWire 3.x, Copyright 2018 by Ryan Cramer
  * https://processwire.com
  * 
- * #pw-summary Manages all custom fields in ProcessWire
+ * #pw-summary Manages all custom fields in ProcessWire, independently of any Fieldgroup. 
+ * #pw-var $fields
+ * #pw-body = 
+ * Each field returned is an object of type `Field`. The $fields API variable is iterable: 
+ * ~~~~~
+ * foreach($fields as $field) {
+ *   echo "<p>Name: $field->name, Type: $field->type, Label: $field->label</p>";
+ * }
+ * ~~~~~
+ * #pw-body
  * 
  * @method Field|null get($key) Get a field by name or id
  * @method bool changeFieldtype(Field $field1, $keepSettings = false)
@@ -309,7 +318,6 @@ class Fields extends WireSaveableItems {
 	 * @param Field|Saveable $item Field to clone
 	 * @param string $name Optionally specify name for new cloned item
 	 * @return bool|Saveable $item Returns the new clone on success, or false on failure
-	 * @throws WireException
 	 *
 	 */
 	public function ___clone(Saveable $item, $name = '') {

wire/core/Inputfield.php

@@ -531,6 +531,7 @@ abstract class Inputfield extends WireData implements Module {
 	 * 
 	 */
 	public function getParents() {
+		/** @var InputfieldWrapper|null $parent */
 		$parent = $this->getParent();
 		if(!$parent) return array();
 		$parents = array($parent);

wire/core/Pagefile.php

@@ -22,7 +22,7 @@
  * @property-read string $filename full disk path to the file on the server. 
  * @property-read string $name Returns the filename without the path, same as the "basename" property.
  * @property-read string $hash Get a unique hash (for the page) representing this Pagefile.
- * @property-read string $tagsArray Get file tags as an array. #pw-group-tags @since 3.0.17
+ * @property-read array $tagsArray Get file tags as an array. #pw-group-tags @since 3.0.17
  * @property int $sort Sort order in database. #pw-group-other
  * @property string $basename Returns the filename without the path.
  * @property string $description Value of the file’s description field (string), if enabled. Note you can also set this property directly.