Updated and refined documentation

[cmaglie]

Please check if the PR fulfills these requirements

See how to contribute

• The PR has no duplicates (please search among the Pull Requests
  before creating one)
• The PR follows
  our contributing guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)
• UPGRADING.md has been updated with a migration guide (for breaking changes)
• configuration.schema.json updated if new parameters are added.

What kind of change does this PR introduce?

• Refined platform specification on installation folder for platforms
• Expanded docs on default directories configuration
• Cleared usage of identification properties

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change, and is titled accordingly?

Other information

Fix #2753

[thernstig]

I also noticed that if I install a platform manually in {directories.user}/hardware/STMicroelectronics/stm32/..., while already having a installation via the Board Manager in {directories.data}/packages/STMicroelectronics/hardware/stm32/2.8.1/..., the one in the user directory takes precedence for what is seen in the Arduino IDE.

Example:

The problem is however, that I had a new version in {directories.user}/hardware/STMicroelectronics/stm32/... with new board variants, but I could not see those in the Board part number: ... menu as expected.

Is this a separate bug? In that it is possible to install a platform manually, and it is seen in the menu, but the actual new additions to the manual installation are not shown?

Also it might be good to mention in these docs what happens if you have the same VENDOR_NAME and ARCHITECTURE in these data and user directory?

[cmaglie]

Is this a separate bug? In that it is possible to install a platform manually, and it is seen in the menu, but the actual new additions to the manual installation are not shown?

Currently, if there are two matching platforms the one installed in the sketchbook should take precedence... but since you're not able to see the new board definitions there could be a regression, I'll check this out.
To avoid confusion, during the development of a platform, we use the "trick" to slightly rename the vendor installed in the sketchbook so instead of:

{directories.user}/hardware/STMicroelectronics/stm32/...

we use for example:

{directories.user}/hardware/STMicroelectronics-dev/stm32/...

This way there is no confusion and both platforms (the original and the "dev") are visible in the IDE.

Also it might be good to mention in these docs what happens if you have the same VENDOR_NAME and ARCHITECTURE in these data and user directory?

Yes good point.

[thernstig]

This way there is no confusion and both platforms (the original and the "dev") are visible in the IDE.

This was not the case for me. I only saw the one as you see in the picture above.

[thernstig]

LGTM (except I saw no mention of what happens there are matching VENDOR+ARCHITECTURE namings in the data and user directory.

[cmaglie]

except I saw no mention of what happens there are matching VENDOR+ARCHITECTURE namings in the data and user directory

I checked, and the Arduino CLI has a bug/regression. The expected behavior is not happening (the platform installed in the sketchbook should take priority over the one installed via Board Manager if they match VENDOR+ARCHITECTURE).

I'm going to open a new issue about this, I'll add the note in the documentation after the bug is fixed.
In the meantime, I'm merging this one.