all: Comments and cosmetics (#8218)

* lib/api: Note ItemStarted and ItemFinished for default filtering.

The reasoning why LocalChangeDetected and RemoteChangeDetected events
are not included in the event stream by default (without explicit
filter mask requested) also holds for the ItemStarted and ItemFinished
events.  They should be excluded as well when we start to break the
API compatibility for some reason.

* gui: Enumerate unused event types in the eventService.

Define constants for the unused event types as well, for completeness'
sake.  They are intentionally not handled in the GUI currently.

* cmd/syncthing: Harmonize uppercase CLI argument placeholders.

Use ALL-UPPERCASE and connecting dashes to distinguish argument
placeholders from literal argument options (e.g. "cpu" or "heap" for
profiling).  The dash makes it clear which words form a single
argument and where a new argument starts.

This style is already used for the "syncthing cli debug file" command.

* lib/model: Simplify event data structure.

Using map[string]interface{} is not necessary when all values are
known to be strings.

cmd/syncthing/cli/errors.go

@@ -27,7 +27,7 @@ var errorsCommand = cli.Command{
 		{
 			Name:      "push",
 			Usage:     "Push an error to active clients",
-			ArgsUsage: "[error message]",
+			ArgsUsage: "ERROR-MESSAGE",
 			Action:    expects(1, errorsPush),
 		},
 		{

cmd/syncthing/cli/operations.go

@@ -39,13 +39,13 @@ var operationCommand = cli.Command{
 		{
 			Name:      "folder-override",
 			Usage:     "Override changes on folder (remote for sendonly, local for receiveonly). WARNING: Destructive - deletes/changes your data.",
-			ArgsUsage: "[folder id]",
+			ArgsUsage: "FOLDER-ID",
 			Action:    expects(1, foldersOverride),
 		},
 		{
 			Name:      "default-ignores",
 			Usage:     "Set the default ignores (config) from a file",
-			ArgsUsage: "path",
+			ArgsUsage: "PATH",
 			Action:    expects(1, setDefaultIgnores),
 		},
 	},

gui/default/syncthing/core/eventService.js

@@ -65,18 +65,25 @@ angular.module('syncthing.core')
             DEVICE_PAUSED: 'DevicePaused',   // Emitted when a device has been paused
             DEVICE_RESUMED: 'DeviceResumed',   // Emitted when a device has been resumed
             DOWNLOAD_PROGRESS: 'DownloadProgress',   // Emitted during file downloads for each folder for each file
+            FAILURE: 'Failure',   // Specific errors sent to the usage reporting server for diagnosis
             FOLDER_COMPLETION: 'FolderCompletion',   //Emitted when the local or remote contents for a folder changes
             FOLDER_REJECTED: 'FolderRejected',   // DEPRECATED: Emitted when a device sends index information for a folder we do not have, or have but do not share with the device in question
             PENDING_FOLDERS_CHANGED: 'PendingFoldersChanged',   // Emitted when pending folders were added / updated (offered by some device, but not shared to them) or removed (folder ignored or added or no longer offered from the remote device)
             FOLDER_SUMMARY: 'FolderSummary',   // Emitted when folder contents have changed locally
             ITEM_FINISHED: 'ItemFinished',   // Generated when Syncthing ends synchronizing a file to a newer version
             ITEM_STARTED: 'ItemStarted',   // Generated when Syncthing begins synchronizing a file to a newer version
+            LISTEN_ADDRESSES_CHANGED: 'ListenAddressesChanged',   // Listen address resolution has changed.
+            LOCAL_CHANGE_DETECTED: 'LocalChangeDetected',   // Generated upon scan whenever the local disk has discovered an updated file from the previous scan.
             LOCAL_INDEX_UPDATED: 'LocalIndexUpdated',   // Generated when the local index information has changed, due to synchronizing one or more items from the cluster or discovering local changes during a scan
+            LOGIN_ATTEMPT: 'LoginAttempt',   // Emitted on every login attempt when authentication is enabled for the GUI.
+            REMOTE_CHANGE_DETECTED: 'RemoteChangeDetected',   // Generated upon scan whenever a file is locally updated due to a remote change.
+            REMOTE_DOWNLOAD_PROGRESS: 'RemoteDownloadProgress',   // DownloadProgress message received from a connected remote device.
             REMOTE_INDEX_UPDATED: 'RemoteIndexUpdated',   // Generated each time new index information is received from a device
             STARTING: 'Starting',   // Emitted exactly once, when Syncthing starts, before parsing configuration etc
             STARTUP_COMPLETED: 'StartupCompleted',   // Emitted exactly once, when initialization is complete and Syncthing is ready to start exchanging data with other devices
             STATE_CHANGED: 'StateChanged',   // Emitted when a folder changes state
             FOLDER_ERRORS: 'FolderErrors',   // Emitted when a folder has errors preventing a full sync
+            FOLDER_WATCH_STATE_CHANGED: 'FolderWatchStateChanged',   // Watcher routine encountered a new error, or a previous error disappeared after retrying.
             FOLDER_SCAN_PROGRESS: 'FolderScanProgress',   // Emitted every ScanProgressIntervalS seconds, indicating how far into the scan it is at.
             FOLDER_PAUSED: 'FolderPaused',   // Emitted when a folder is paused
             FOLDER_RESUMED: 'FolderResumed',   // Emitted when a folder is resumed

lib/api/api.go

@@ -59,6 +59,8 @@ import (
 )
 
 const (
+	// Default mask excludes these very noisy event types to avoid filling the pipe.
+	// FIXME: ItemStarted and ItemFinished should be excluded for the same reason.
 	DefaultEventMask      = events.AllEvents &^ events.LocalChangeDetected &^ events.RemoteChangeDetected
 	DiskEventMask         = events.LocalChangeDetected | events.RemoteChangeDetected
 	EventSubBufferSize    = 1000

lib/model/folder.go

@@ -1038,7 +1038,7 @@ func (f *folder) setWatchError(err error, nextTryIn time.Duration) {
 	f.watchErr = err
 	f.watchMut.Unlock()
 	if err != prevErr {
-		data := map[string]interface{}{
+		data := map[string]string{
 			"folder": f.ID,
 		}
 		if prevErr != nil {