Fix documentation and code comments

Co-authored-by: per1234 <accounts@perglass.com>

Author: silvanocerza

arduino/cores/packagemanager/loader.go

@@ -664,7 +664,7 @@ func (pm *PackageManager) loadDiscoveries(release *cores.PlatformRelease) []*sta
 
 	discoveryIDs := discoveryProperties.FirstLevelOf()
 	delete(discoveryIDs, "required")
-	// Get the list of tools only we if have there are discoveries that use Direct discovery integration.
+	// Get the list of tools only if there are discoveries that use Direct discovery integration.
 	// See:
 	// https://github.com/arduino/tooling-rfcs/blob/main/RFCs/0002-pluggable-discovery.md#direct-discovery-integration-not-recommended
 	// We need the tools only in that case since we might need some tool's

arduino/discovery/discoverymanager/discoverymanager.go

@@ -27,7 +27,7 @@ type DiscoveryManager struct {
 	globalEventCh chan *discovery.Event
 }
 
-// New creates a new DiscoveriesManager
+// New creates a new DiscoveryManager
 func New() *DiscoveryManager {
 	return &DiscoveryManager{
 		discoveries:   map[string]*discovery.PluggableDiscovery{},

cli/arguments/reference.go

@@ -36,7 +36,7 @@ func (r *Reference) String() string {
 }
 
 // ParseReferences is a convenient wrapper that operates on a slice of strings and
-// calls ParseReferenceArg for each of them. It returns at the first invalid argument.
+// calls ParseReference for each of them. It returns at the first invalid argument.
 func ParseReferences(args []string, parseArch bool) ([]*Reference, error) {
 	ret := []*Reference{}
 	for _, arg := range args {
@@ -49,7 +49,7 @@ func ParseReferences(args []string, parseArch bool) ([]*Reference, error) {
 	return ret, nil
 }
 
-// ParseReference parses a string and return a ReferenceArg object. If `parseArch` is passed,
+// ParseReference parses a string and returns a Reference object. If `parseArch` is passed,
 // the method also tries to parse the architecture bit, i.e. string must be in the form
 // "packager:arch@version", useful to represent a platform (or core) name.
 func ParseReference(arg string, parseArch bool) (*Reference, error) {

docs/UPGRADING.md

@@ -4,9 +4,9 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## Unreleased
 
-### gRPC interface `UploadRequest`, `UploadUsingProgrammerRequest`, `BurnBootloaderRequest`, `DetectedPort` arguments changes
+### gRPC interface `UploadRequest`, `UploadUsingProgrammerRequest`, `BurnBootloaderRequest`, `DetectedPort` field changes
 
-`UploadRequest`, `UploadUsingProgrammerRequest` and `BurnBootloaderRequest` had their `port` argument change from type
+`UploadRequest`, `UploadUsingProgrammerRequest` and `BurnBootloaderRequest` had their `port` field change from type
 `string` to `Port`.
 
 `Port` contains the following information:
@@ -57,12 +57,12 @@ message DetectedPort {
 
 The properties previously contained directly in the message are now stored in the `port` property.
 
-This changes are necessary for the Pluggable Discovery.
+These changes are necessary for the Pluggable Discovery.
 
 ### gRPC interface `BoardListItem` change
 
-The `vid` and `pid` properties of the `BoardListItem` have been removed. They used to only be available when requesting
-connected board lists, now that information is stored in the `port` property of `DetectedPort`.
+The `vid` and `pid` fields of the `BoardListItem` message have been removed. They used to only be available when
+requesting connected board lists, now that information is stored in the `port` field of `DetectedPort`.
 
 ### Change public library interface
 

docs/package_index_json-specification.md

@@ -217,10 +217,10 @@ Finally, let's see how `PLATFORMS` are made.
             { "packager": "arduino", "name": "avr-gcc", "version": "4.8.1-arduino5" },
             { "packager": "arduino", "name": "avrdude", "version": "6.0.1-arduino5" }
           ],
-         "discoveryDependencies": [
-           { "packager": "arduino", "name": "serial-discovery" },
-           { "packager": "arduino", "name": "mdns-discovery" }
-         ]
+          "discoveryDependencies": [
+            { "packager": "arduino", "name": "serial-discovery" },
+            { "packager": "arduino", "name": "mdns-discovery" }
+          ]
         },
 ```
 

docs/platform-specification.md

@@ -627,61 +627,48 @@ variables.
 
 #### Pluggable Discovery
 
-Discovery tools are a special kind of tools that are used to find supported boards, a platform must declare one or more
-Pluggable Discoveries in its `platform.txt`. It's ok to use another platform discovery or the builtin ones if necessary.
+Discovery tools are a special kind of tool used to find supported boards. A platform must declare one or more Pluggable
+Discoveries in its [`platform.txt`](#platformtxt). Discoveries can be referenced from other packages, including the
+`builtin` dummy package which contains the traditional discoveries.
 
-There are two different syntaxes to declare discoveries, if the platform uses just one discovery:
+There are two different syntaxes to declare discoveries. If the platform uses just one discovery:
 
-```
-discovery.required=PLATFORM:DISCOVERY_NAME
-```
+    discovery.required=VENDOR_ID:DISCOVERY_NAME
 
 instead if it needs multiple discoveries:
 
-```
-discovery.required.0=PLATFORM:DISCOVERY_ID_1
-discovery.required.1=PLATFORM:DISCOVERY_ID_2
-```
+    discovery.required.0=VENDOR_ID:DISCOVERY_0_NAME
+    discovery.required.1=VENDOR_ID:DISCOVERY_1_NAME
 
-A platform that supports only boards connected to the serial can easily use the builtin `serial-discovery` without
-creating a custom Pluggable Discovery:
+A platform that supports only boards connected via serial ports can easily use the `builtin` package's
+`serial-discovery` without creating a custom Pluggable Discovery:
 
-```
-discovery.required=builtin:serial-discovery
-```
+    discovery.required=builtin:serial-discovery
 
-if it supports also boards connected to the network it can use the builtin `mdns-discovery`:
+if it also supports boards connected via the network, it can use the `builtin` package's `mdns-discovery`:
 
-```
-discovery.required.0=builtin:serial-discovery
-discovery.required.1=builtin:mdns-discovery
-```
+    discovery.required.0=builtin:serial-discovery
+    discovery.required.1=builtin:mdns-discovery
 
-Since the above syntax requires adding a discovery in the `discoveryDependencies` field in the platform
-`package_index.json` it might be cumbersome to do it before releasing it so we also provide another syntax to ease
-development:
+Since the above syntax requires specifying a discovery via the `discoveryDependencies` field of the platform's
+[package index](package_index_json-specification.md), it might be cumbersome to use with manual installations. So we
+provide another syntax to ease development and beta testing:
 
-```
-discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE
-```
+    discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE
 
 `DISCOVERY_ID` must be replaced by a unique identifier for the particular discovery and `DISCOVERY_RECIPE` must be
 replaced by the command line to launch the discovery. An example could be:
 
-```
-## Teensy Ports Discovery
-discovery.teensy.pattern="{runtime.tools.teensy_ports.path}/hardware/tools/teensy_ports" -J2
-```
+    ## Teensy Ports Discovery
+    discovery.teensy.pattern="{runtime.tools.teensy_ports.path}/hardware/tools/teensy_ports" -J2
 
-We strongly recommend not using this syntax on released platforms but only for development purposes.
+We strongly recommend using this syntax only for development purposes and not on released platforms.
 
 For backward compatibility, if a platform does not declare any discovery (using the `discovery.*` properties in
-`platform.txt`) it will automatically inherits `builtin:serial-discovery` and `builtin:mdns-discovery` (but not other
-builtin discoveries that may be possibly added in the future). This will allow all legacy non-pluggable platforms to
-migrate to pluggable discovery without disruption.
+`platform.txt`) it will automatically inherit `builtin:serial-discovery` and `builtin:mdns-discovery` (but not other
+builtin discoveries that may be possibly added in the future).
 
-For detailed information see the [Pluggable Discovery specification](pluggable-discovery-specification.md)
-documentation.
+For detailed information, see the [Pluggable Discovery specification](pluggable-discovery-specification.md).
 
 #### Verbose parameter
 
@@ -719,8 +706,8 @@ The **upload.tool.<protocol_name\>** property determines the tool to be used for
     leonardo.upload.tool.network=arduino_ota
     [......]
 
-When the user tries to upload using a certain protocol but the board doesn't support it it will fallback to `default` if
-specified. A board can always specify a `default` protocol even if others are defined:
+Multiple protocols can be defined for each board. When the user tries to upload using a protocol not supported by the
+board, it will fallback to `default` if one was defined:
 
     [......]
     uno.upload.tool.default=avrdude
@@ -729,8 +716,8 @@ specified. A board can always specify a `default` protocol even if others are de
     leonardo.upload.tool.network=arduino_ota
     [......]
 
-`default` is also used when no upload address is provided by the user, this can be done only for boards that use upload
-tools with builtin port detection like `openocd`.
+`default` is also used when no upload address is provided by the user. This can be used with tools that have built-in
+port detection (e.g., `openocd`).
 
 For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported:
 
@@ -777,19 +764,19 @@ If a platform supports Pluggable Discovery it can also use the port's properties
 the following port metadata coming from a pluggable discovery:
 
     {
-        "eventType": "add",
-        "port": {
-            "address": "/dev/ttyACM0",
-            "label": "ttyACM0",
-            "protocol": "serial",
-            "protocolLabel": "Serial Port (USB)",
-            "properties": {
-                "pid": "0x804e",
-                "vid": "0x2341",
-                "serialNumber": "EBEABFD6514D32364E202020FF10181E",
-                "name": "ttyACM0"
-            }
+      "eventType": "add",
+      "port": {
+        "address": "/dev/ttyACM0",
+        "label": "ttyACM0",
+        "protocol": "serial",
+        "protocolLabel": "Serial Port (USB)",
+        "properties": {
+          "pid": "0x804e",
+          "vid": "0x2341",
+          "serialNumber": "EBEABFD6514D32364E202020FF10181E",
+          "name": "ttyACM0"
         }
+      }
     }
 
 will be available on the recipe as the variables:
@@ -808,17 +795,17 @@ will be available on the recipe as the variables:
 Here another example:
 
     {
-    "eventType": "add",
-    "port": {
+      "eventType": "add",
+      "port": {
         "address": "192.168.1.232",
         "label": "SSH on my-board (192.168.1.232)",
         "protocol": "ssh",
         "protocolLabel": "SSH Network port",
         "properties": {
-        "macprefix": "AA:BB:CC",
-        "macaddress": "AA:BB:CC:DD:EE:FF"
+          "macprefix": "AA:BB:CC",
+          "macaddress": "AA:BB:CC:DD:EE:FF"
         }
-    }
+      }
     }
 
 that is translated to:
@@ -831,7 +818,7 @@ that is translated to:
     {upload.port.properties.macaddress} = AA:BB:CC:DD:EE:FF
     {serial.port} = 192.168.1.232                  # for backward compatibility
 
-This configuration, together with protocol selection, allows to remove the hardcoded `network_pattern`, now we can
+This configuration, together with protocol selection, allows to remove the hardcoded `network_pattern`. Now we can
 replace the legacy recipe (split into multiple lines for clarity):
 
     tools.bossac.upload.network_pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
@@ -847,25 +834,22 @@ with:
 #### User provided fields
 
 Some upload recipes might require custom fields that must be provided by the user, like username and password to upload
-over the network. In this case the recipe must use the special placeholder {upload.field.FIELD_NAME} where FIELD_NAME
-must be declared separately in the recipe using the following format:
+over the network. In this case the recipe must use the special placeholder **{upload.field.FIELD_NAME}**, where
+**FIELD_NAME** must be declared separately in the recipe using the following format:
 
     tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME=FIELD_LABEL
     tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME.secret=true
 
-FIELD_LABEL is the label shown in the graphical prompt to ask the user to enter the value of the field. The secret
-property is optional and it should be set to true if the field is a secret (like passwords or token).
+**FIELD_LABEL** is the label shown in the graphical prompt where the user is asked to enter the value for the field.
+
+The optional **secret** property should be set to `true` if the field is a secret (like a password or token).
 
-Let’s see how a complete example will look like:
+Let's see a complete example:
 
     tools.arduino_ota.upload.field.username=Username
     tools.arduino_ota.upload.field.password=Password
     tools.arduino_ota.upload.field.password.secret=true
-    tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
-                                    -address {upload.port.address} -port 65280
-                                    -username "{upload.field.username}
-                                    -password "{upload.field.password}"
-                                    -sketch "{build.path}/{build.project_name}.bin"
+    tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA" -address {upload.port.address} -port 65280 -username "{upload.field.username} -password "{upload.field.password}" -sketch "{build.path}/{build.project_name}.bin"
 
 #### Upload verification
 
@@ -943,7 +927,8 @@ The `program` action is triggered via the **Sketch > Upload Using Programmer** f
 compiled sketch to a board using an external programmer.
 
 The **program.tool** property determines the tool to be used for this action. This property is typically defined for
-each programmer in [programmers.txt](#programmerstxt) and uses the same syntax as `upload` action:
+each programmer in [programmers.txt](#programmerstxt) and uses the same syntax as
+[the `upload` action](#sketch-upload-configuration):
 
     [......]
     usbasp.program.tool.serial=avrdude
@@ -983,15 +968,16 @@ the board.
 1. `bootloader` is used to flash the bootloader to the board
 
 The **bootloader.tool** property determines the tool to be used for the `erase` and `bootloader` actions both. This
-property is typically defined for each board in boards.txt and uses the same syntax as `upload` action:
+property is typically defined for each board in boards.txt and uses the same syntax as
+[the `upload` action](#sketch-upload-configuration):
 
     [......]
     uno.bootloader.tool.serial=avrdude
     [......]
-    leonardo.upload.tool.serial=avrdude
-    leonardo.upload.tool.network=arduino_ota
+    leonardo.bootloader.tool.serial=avrdude
+    leonardo.bootloader.tool.network=arduino_ota
     [......]
-    duemilanove.upload.tool.default=avrdude
+    duemilanove.bootloader.tool.default=avrdude
     [......]
 
 For backward compatibility with IDE 1.8.15 and older the previous syntax is still supported:
@@ -1217,7 +1203,3 @@ software is in use:
   This behavior
   [can be configured](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_core_install/#options)
 - **Arduino Pro IDE**: (since 0.1.0) runs the script for any installed platform.
-
-```
-
-```