Issue 616 - updated documentation

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 
+* Modified various md documentation files to reflect work done since last documentation update as per [Issue 616](https://github.com/rubrikinc/rubrik-sdk-for-powershell/issues/616)
 * `New-RubrikFilesetTemplate` now has type data assigned [Issue 611](https://github.com/rubrikinc/rubrik-sdk-for-powershell/issues/611)
 * Removed -Body $body from `Get-RubrikClusterInfo` when it passes variables to Submit-Request as per [Issue 604](https://github.com/rubrikinc/rubrik-sdk-for-powershell/issues/604)
 * Added default parametersets, positional attributes to name parameters, and removed pipeline support from name for the following cmdlets: `Get-RubrikSLA`, `Get-RubrikArchive`, `Get-RubrikClusterNetworkInterface`, `Get-RubrikDatabase`, `Get-RubrikDatabaseMount`, `Get-RubrikFileset`, `Get-RubrikFilesetTemplate`, `Get-RubrikGuestOSCredential`,`Get-RubrikHost`,`Get-RubrikHypervHost`, `Get-RubrikHyperVVM`,`Get-RubrikLogShipping`,`Get-RubrikManagedVolume`,`Get-RubrikNutanixCLuster`,`Get-RubrikNutanixVM`,`Get-RubrikObjectStoreArchive`,`Get-RubrikOracleDB`,`Get-RubrikOrganization`,`Get-RubrikQstarArchive`,`Get-RubrikReplicationSource`,`Get-RubrikReplicationTarget`,`Get-RubrikSQLInstance`, `Get-RubrikScvmm`, `Get-RubrikSmbDomain`, `Get-RubrikUnmanagedObject`, `Get-RubrikUser`, `Get-RubrikvApp`, `Get-RubrikVCD`, `Get-RubrikVMwareCluster`, `Get-RubrikVMwareHost`, `Get-RubrikVMwareDatastore`, and `Get-RubrikVMwareDatacenter`.  This provides a more user friendly experience by allowing users to simply enter `Get-RubrikSLA MySLA` rather than `Get-RubrikSLA -Name MySQL`.  Removing pipeline support from name also ensures that when utilizing pipeline, ID queries are always performed. IE `Get-RubrikSLA MySLA | Get-RubrikSLA ` will first use the basic name filter for the left hand of the pipeline, however the second will pick up the id to perform an id based parameter.

docs/user-documentation/contribution.md

@@ -222,3 +222,18 @@ Param(
 
 The final step is to update the module manifest and add the new function to the `FunctionsToExport` value. This is done in the `Rubrik\Rubrik.psd1` file.
 
+## Notable Details
+
+The Rubrik SDK for PowerShell follows a few design and syntax guidelines, each highlighted below:
+
+### Usage of Switch over Boolean
+
+To maintain consistency with the existing module code the usage of Boolean parameters is prohibited. Instead, a Switch parameter should be utilized to handle true/false situations. Let's take a look at the `New-RubrikMount` cmdlet as an example. The body defined within `Get-RubrikAPIData` contains a boolean entry named `powerOn` which control whether the newly mounted VM is powered on or not.  It's default, if not included, is to leave the VM powered off. Therefore, within the `New-RubrikMount` code we explicitly remove it if the `PowerOn` switch parameter is not specified
+
+```text
+if(-not $PSBoundParameters.ContainsKey('PowerOn')) { $Resources.Body.Remove('powerOn') }
+```
+
+### Creation of Custom View Definitions
+
+The Rubrik SDK for PowerShell supports the creation of custom typename files to provide custom view definitions for various objects returned from cmdlets. For example, the `Get-RubrikSLA` cmdlet applies a custom typename file `Rubrik.SLADomain.ps1xml` to its returned results. The `Rubrik.SLADomain.ps1xml` file controls what properties are displayed by default to the PowerShell console. The objects themselves still contain all properties, which can be viewed by piping the results to `Select *` (I.E. `Get-RubrikSLA | Select *`).  Object typename files are created within the `ObjectDefinitions` folder and applied by assigning the `ObjectTName` variable to match that of the `TypeName` definition within `Get-RubrikAPIData`. The TypeName file must also be added to the `FormatsToProcess` exports within `rubrik.psd1`.

docs/user-documentation/faq.md

@@ -1,4 +1,48 @@
 # FAQ
 
-This section will contain a list of questions that have been received \(and answered\) by the Project Team.
+This section will contain a list of common questions that have been received (and answered) by the Project Team.
+
+- [How do I install the devel branch of the Rubrik SDK for PowerShell?](#how-do-i-install-the-devel-branch-of-the-rubrik-sdk-for-powershell)
+- [Why do I see only a subset of object properties?](#why-do-i-see-only-a-subset-of-object-properties)
+- [Why is the returned data different when I filter objects based on name vs based on their id value?](#why-is-the-returned-data-different-when-i-filter-objects-based-on-name-vs-based-on-their-id-value)
+
+## How do I install the devel branch of the Rubrik SDK for PowerShell?
+
+In order to test new features or cmdlets which have been developed you may wish to run the `devel` branch of the Rubrik SDK for PowerShell. All new functionality first lands within the `devel` branch before it is migrated to `master` during a module release. The easiest way to install and test the `devel` branch is as follows:
+1. Clone the GitHub repository to a local folder
+
+    `git clone https://github.com/rubrikinc/rubrik-sdk-for-powershell c:\test\`
+
+1. Traverse to the local directory the module was cloned in and checkout the `devel` branch
+
+    `cd c:\test\
+    git checkout devel`
+
+1. Import the Rubrik Module, specifying the path to the newly cloned repository
+
+    `Import-Module c:\test\Rubrik -Force`
+
+
+## Why do I see only a subset of object properties?
+
+By default, custom view definitions are applied to the output of some results that cmdlets return. For instance, running `Get-RubrikSLA` only shows the Name, Base Frequency, Object Count, Archival Location, Replication Location and Id by default.
+
+![](../img/get-rubrikslacustom.png)
+
+Rest assured though, all properties are returned and can be viewed by simply piping the cmdlet to Select * (`Get-RubrikSLA | Select *`) or referencing the property directly (`(Get-RubrikSLA).numVms`).
+
+The application of custom view definitions may also be turned on and off with the configuration of the `ApplyCustomViewDefinitions` module option as well.
+
+```text
+Set-RubrikModuleOption -OptionName "ApplyCustomViewDefinitions" -OptionValue "False"
+```
+
+## Why is the returned data different when I filter objects based on name vs based on their id value?
+
+Many Rubrik API endpoints are designed in such a way that they provide lists of objects as a response when querying a simple object type, and a more detailed response when sending the actual ID of the object. For instance, we are able to get a list of VMs by sending a GET request to the `/vmware/vm` endpoint. We can, if we desire, shorten this list by adding a `name` filter into the query. This process is the same as running `Get-RubrikVM -Name "VMName"`. By sending the id to the endpoint `/vmware/vm/{id}` we essentially ask for a more detailed response, equivalent to running `Get-RubrikVM -ID "12345"`. That said, we are able to use the `-Name` parameter along with the `-DetailedObject` parameter to retrieve the detailed response just as if we had passed the `-Id` parameter.
+
+```text
+Get-RubrikVM -Name "VMName" -DetailedObject
+```
+
 

docs/user-documentation/project_architecture.md

@@ -9,6 +9,8 @@ This page contains details on the artifacts found within the repository.
 * Rubrik: The parent folder containing the module
   * Private: Private functions that are used internally by the module
   * Public: Published functions that are available to the PowerShell session
+  * ObjectDefinitions: Custom TypeName view definitions applicable to Rubrik objects
+  * OptionsDefault: Template of module options and default parameters
   * Rubrik.psd1: Module manifest
   * Rubrik.psm1: Script module file
 

docs/user-documentation/requirements.md

@@ -7,5 +7,4 @@ The code assumes that you've already deployed at least one Rubrik Brik into your
 3. Rubrik version 2.2 or higher
 4. \(optional\) [`Windows Management Framework 5.0`](https://www.microsoft.com/en-us/download/details.aspx?id=50395)
 
-Note: Although an alpha build of PowerShell exists for Linux and Mac OS environments, the code is currently being written and validated using a Microsoft Windows Server environment.