Improve documentation of NodePermissions

While reading the documentation of NodePermissions::buildPermissions() I noticed that the following documentation is incorrect, this contains the full NodeType object, not only the machine name:

/**
 * Builds a standard list of node permissions for a given type.
 *
 * @param \Drupal\node\Entity\NodeType $type
 *   The machine name of the node type.
 *
 * @return array
 *   An array of permission names and descriptions.
 */
protected function buildPermissions(NodeType $type) {
}

Let's do an overhaul of the entire documentation while we're at it.

Beta: This is only API docs. Commit any time.