update cli docs (#3310)

updates and improves cli docs.  in part for easier reading and explanation.  in part to remove all references to resource owner flags in details and restore.

---

#### Does this PR need a docs update or release note?

- [x] ✅ Yes, it's included

#### Type of change

- [x] 🐛 Bugfix

#### Test Plan

- [x] 💪 Manual

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Graph requests now automatically retry in case of a Bad Gateway or Gateway Timeout.
 - POST Retries following certain status codes (500, 502, 504) will re-use the post body instead of retrying with a no-content request.
 - Fix nil pointer exception when running an incremental backup on SharePoint where the base backup used an older index data format.
+- --user and --mailbox flags (already not supported) have been removed from CLI examples for details and restore commands.
 
 ## [v0.7.0] (beta) - 2023-05-02
 

src/cli/backup/exchange.go

@@ -49,18 +49,18 @@ corso backup create exchange --mailbox '*'`
 	exchangeServiceCommandDeleteExamples = `# Delete Exchange backup with ID 1234abcd-12ab-cd34-56de-1234abcd
 corso backup delete exchange --backup 1234abcd-12ab-cd34-56de-1234abcd`
 
-	exchangeServiceCommandDetailsExamples = `# Explore items in backup 1234abcd-12ab-cd34-56de-1234abcd (Alice's backup)
+	exchangeServiceCommandDetailsExamples = `# Explore items in Alice's latest backup (1234abcd...)
-corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --mailbox alice@example.com
+corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd
 
-# Explore Alice's emails with subject containing "Hello world" in folder "Inbox" from a specific backup 
+# Explore emails in the folder "Inbox" with subject containing "Hello world"
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
     --email-subject "Hello world" --email-folder Inbox
 
-# Explore Bobs's events occurring after start of 2022 from a specific backup
+# Explore calendar events occurring after start of 2022
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
     --event-starts-after 2022-01-01T00:00:00
 
-# Explore Alice's contacts with name containing Andy from a specific backup
+# Explore contacts named Andy
 corso backup details exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
     --contact-name Andy`
 )

src/cli/backup/onedrive.go

@@ -43,16 +43,16 @@ corso backup create onedrive --user '*'`
 	oneDriveServiceCommandDeleteExamples = `# Delete OneDrive backup with ID 1234abcd-12ab-cd34-56de-1234abcd
 corso backup delete onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd`
 
-	oneDriveServiceCommandDetailsExamples = `# Explore Alice's files from backup 1234abcd-12ab-cd34-56de-1234abcd 
+	oneDriveServiceCommandDetailsExamples = `# Explore items in Bob's latest backup (1234abcd...)
-corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --user alice@example.com
+corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd
 
-# Explore Alice or Bob's files with name containing "Fiscal 22" in folder "Reports"
+# Explore files in the folder "Reports" named "Fiscal 22"
 corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com,bob@example.com  --file-name "Fiscal 22" --folder "Reports"
+    --file-name "Fiscal 22" --folder "Reports"
 
-# Explore Alice's files created before end of 2015 from a specific backup
+# Explore files created before the end of 2015
 corso backup details onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com --file-created-before 2015-01-01T00:00:00`
+    --file-created-before 2015-01-01T00:00:00`
 )
 
 // called by backup.go to map subcommands to provider-specific handling.

src/cli/backup/sharepoint.go

@@ -40,10 +40,10 @@ const (
 )
 
 const (
-	sharePointServiceCommandCreateExamples = `# Backup SharePoint data for a Site
+	sharePointServiceCommandCreateExamples = `# Backup SharePoint data in the HR Site
-corso backup create sharepoint --site <siteURL>
+corso backup create sharepoint --site https://example.com/hr
 
-# Backup SharePoint for two sites: HR and Team
+# Backup SharePoint for the HR and Team sites
 corso backup create sharepoint --site https://example.com/hr,https://example.com/team
 
 # Backup all SharePoint data for all Sites
@@ -52,16 +52,20 @@ corso backup create sharepoint --site '*'`
 	sharePointServiceCommandDeleteExamples = `# Delete SharePoint backup with ID 1234abcd-12ab-cd34-56de-1234abcd
 corso backup delete sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd`
 
-	sharePointServiceCommandDetailsExamples = `# Explore a site's files from backup 1234abcd-12ab-cd34-56de-1234abcd
+	sharePointServiceCommandDetailsExamples = `# Explore items in the HR site's latest backup (1234abcd...)
 corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd
 
-# Find all files that were created before a certain date.
+# Explore files in the folder "Reports" named "Fiscal 22"
+corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \
+    --file-name "Fiscal 22" --folder "Reports"
+
+# Explore files in the folder ""Display Templates/Style Sheets"" created before the end of 2015.
 corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \
     --file-created-before 2015-01-01T00:00:00 --folder "Display Templates/Style Sheets"
 
-# Find all files within a specific library.
+# Explore all files within the document library "Work Documents"
 corso backup details sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --library documents --folder "Display Templates/Style Sheets"
+    --library "Work Documents"
 `
 )
 

src/cli/restore/exchange.go

@@ -44,18 +44,19 @@ const (
 	exchangeServiceCommand          = "exchange"
 	exchangeServiceCommandUseSuffix = "--backup <backupId>"
 
-	exchangeServiceCommandRestoreExamples = `# Restore emails with ID 98765abcdef and 12345abcdef from a specific backup
+	//nolint:lll
+	exchangeServiceCommandRestoreExamples = `# Restore emails with ID 98765abcdef and 12345abcdef from Alice's last backup (1234abcd...)
 corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --email 98765abcdef,12345abcdef
 
-# Restore Alice's emails with subject containing "Hello world" in "Inbox" from a specific backup
+# Restore emails with subject containing "Hello world" in the "Inbox"
 corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com --email-subject "Hello world" --email-folder Inbox
+    --email-subject "Hello world" --email-folder Inbox
 
-# Restore Bobs's entire calendar from a specific backup
+# Restore an entire calendar
 corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user bob@example.com --event-calendar Calendar
+    --event-calendar Calendar
 
-# Restore contact with ID abdef0101 from a specific backup
+# Restore the contact with ID abdef0101
 corso restore exchange --backup 1234abcd-12ab-cd34-56de-1234abcd --contact abdef0101`
 )
 

src/cli/restore/onedrive.go

@@ -46,19 +46,19 @@ const (
 	oneDriveServiceCommand          = "onedrive"
 	oneDriveServiceCommandUseSuffix = "--backup <backupId>"
 
-	oneDriveServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef
+	oneDriveServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef in Bob's last backup (1234abcd...)
 corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef
 
-# Restore file with ID 98765abcdef along with its associated permissions
+# Restore the file with ID 98765abcdef along with its associated permissions
 corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef --restore-permissions
 
-# Restore Alice's file named "FY2021 Planning.xlsx in "Documents/Finance Reports" from a specific backup
+# Restore files named "FY2021 Planning.xlsx in "Documents/Finance Reports"
 corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd \
-    --user alice@example.com --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports"
+    --file "FY2021 Planning.xlsx" --folder "Documents/Finance Reports"
 
-# Restore all files from Bob's folder that were created before 2020 when captured in a specific backup
+# Restore all files and folders in folder "Documents/Finance Reports" that were created before 2020
 corso restore onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd 
-    --user bob@example.com --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00`
+    --folder "Documents/Finance Reports" --file-created-before 2020-01-01T00:00:00`
 )
 
 // `corso restore onedrive [<flag>...]`

src/cli/restore/sharepoint.go

@@ -44,20 +44,20 @@ const (
 	sharePointServiceCommandUseSuffix = "--backup <backupId>"
 
 	//nolint:lll
-	sharePointServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef
+	sharePointServiceCommandRestoreExamples = `# Restore file with ID 98765abcdef in Bob's latest backup (1234abcd...)
 corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd --file 98765abcdef
 
-# Restore a file named "ServerRenderTemplate.xsl in "Display Templates/Style Sheets".
+# Restore files named "ServerRenderTemplate.xsl in the folder "Display Templates/Style Sheets".
 corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd \
     --file "ServerRenderTemplate.xsl" --folder "Display Templates/Style Sheets"
 
-# Restore all files that were created before 2020.
+# Restore all files in the folder "Display Templates/Style Sheets" that were created before 2020.
 corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd 
     --file-created-before 2020-01-01T00:00:00 --folder "Display Templates/Style Sheets"
 
-# Restore all files in a certain library.
+# Restore all files in the "Documents" library.
 corso restore sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd 
-    --library documents --folder "Display Templates/Style Sheets" `
+    --library Documents --folder "Display Templates/Style Sheets" `
 )
 
 // `corso restore sharepoint [<flag>...]`