From cacc78dcbeff77c808d91328163c2cbe526a1938 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 26 Jul 2022 10:42:32 -0700 Subject: [PATCH 1/2] Replace IDE 2.x configuration file content with link to source Arduino IDE 2.x allows the user to customize the output of the "Auto Format" feature via a configuration file. This system is documented in the "Customizing the Auto Formatter Feature" tutorial. When the user customizes the formatter, their configuration file is used exclusively by the formatter tool rather than being merged into the standard configuration. Since the user is likely only interested in modifying a small number of specific aspect of the standard configuration (e.g., wishing to use "broken" rather than "attached" braces), they will find it convenient to use Arduino's standard configuration as a base for their custom configuration. For this reason, the standard configuration is offered in the tutorial. Previously, the full YAML code of the standard configuration was included in the tutorial page itself. This was the best approach at the time the tutorial was created because what was the canonical source in the Arduino IDE code base is in a format not usable in this application. Since that time, the ClangFormat native YAML file has been published in a dedicated permanent location where it is hosted as the canonical source for all projects that use the configuration. This enabled the removal of the configuration code from the tutorial, replaced by a link to the source file. This change provides the following benefits: ### Reduce maintenance burden The configuration code must be updated periodically in parallel to bumps of the version of ClangFormat used by Arduino IDE 2.x and other Arduino development tools. This is handled as a matter of course in the canonical source file, but the copy hosted in the tutorial content would have needed updates as well (or else become outdated). Pointing the reader to the source ensures they will always have the current configuration without any need to maintain the documentation content. ### Improves approachability of tutorial The configuration code added a large block of complex YAML to the tutorial. Although it will be necessary for the reader to eventually work with this code, they don't have any need to browse through it while reading the tutorial. So having the code as part of the tutorial content didn't add anything of value and also harmed the readability. --- .../content.md | 147 +----------------- 1 file changed, 1 insertion(+), 146 deletions(-) diff --git a/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md b/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md index aea59676e7..58dc6e34fd 100644 --- a/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md +++ b/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md @@ -65,152 +65,7 @@ Here you can find the default formatting file used in the Arduino IDE 2.0. If yo ***Please note that the custom configuration file completely overrides the Arduino default configuration, rather than merging with it. Any configuration option you don't set in your custom file will be set to the ClangFormat default value.*** -```cpp ---- -Language: Cpp -# LLVM is the default style setting, used when a configuration option is not set here -BasedOnStyle: LLVM -AccessModifierOffset: -2 -AlignAfterOpenBracket: Align -AlignConsecutiveAssignments: false -AlignConsecutiveBitFields: false -AlignConsecutiveDeclarations: false -AlignConsecutiveMacros: false -AlignEscapedNewlines: DontAlign -AlignOperands: Align -AlignTrailingComments: true -AllowAllArgumentsOnNextLine: true -AllowAllConstructorInitializersOnNextLine: true -AllowAllParametersOfDeclarationOnNextLine: true -AllowShortBlocksOnASingleLine: Always -AllowShortCaseLabelsOnASingleLine: true -AllowShortEnumsOnASingleLine: true -AllowShortFunctionsOnASingleLine: Empty -AllowShortIfStatementsOnASingleLine: Always -AllowShortLambdasOnASingleLine: Empty -AllowShortLoopsOnASingleLine: true -AlwaysBreakAfterDefinitionReturnType: None -AlwaysBreakAfterReturnType: None -AlwaysBreakBeforeMultilineStrings: false -AlwaysBreakTemplateDeclarations: No -BinPackArguments: true -BinPackParameters: true -# Only used when "BreakBeforeBraces" set to "Custom" -BraceWrapping: - AfterCaseLabel: false - AfterClass: false - AfterControlStatement: Never - AfterEnum: false - AfterFunction: false - AfterNamespace: false - #AfterObjCDeclaration: - AfterStruct: false - AfterUnion: false - AfterExternBlock: false - BeforeCatch: false - BeforeElse: false - BeforeLambdaBody: false - BeforeWhile: false - IndentBraces: false - SplitEmptyFunction: false - SplitEmptyRecord: false - SplitEmptyNamespace: false -# Java-specific -#BreakAfterJavaFieldAnnotations: -BreakBeforeBinaryOperators: NonAssignment -BreakBeforeBraces: Attach -BreakBeforeTernaryOperators: true -BreakConstructorInitializers: BeforeColon -BreakInheritanceList: BeforeColon -BreakStringLiterals: false -ColumnLimit: 0 -# "" matches none -CommentPragmas: "" -CompactNamespaces: false -ConstructorInitializerAllOnOneLineOrOnePerLine: true -ConstructorInitializerIndentWidth: 2 -ContinuationIndentWidth: 2 -Cpp11BracedListStyle: false -DeriveLineEnding: true -DerivePointerAlignment: true -DisableFormat: false -# Docs say "Do not use this in config files". The default (LLVM 11.0.1) is "false". -#ExperimentalAutoDetectBinPacking: -FixNamespaceComments: false -ForEachMacros: [] -IncludeBlocks: Preserve -IncludeCategories: [] -# "" matches none -IncludeIsMainRegex: "" -IncludeIsMainSourceRegex: "" -IndentCaseBlocks: true -IndentCaseLabels: true -IndentExternBlock: Indent -IndentGotoLabels: false -IndentPPDirectives: None -IndentWidth: 2 -IndentWrappedFunctionNames: false -InsertTrailingCommas: None -# Java-specific -#JavaImportGroups: -# JavaScript-specific -#JavaScriptQuotes: -#JavaScriptWrapImports -KeepEmptyLinesAtTheStartOfBlocks: true -MacroBlockBegin: "" -MacroBlockEnd: "" -# Set to a large number to effectively disable -MaxEmptyLinesToKeep: 100000 -NamespaceIndentation: None -NamespaceMacros: [] -# Objective C-specific -#ObjCBinPackProtocolList: -#ObjCBlockIndentWidth: -#ObjCBreakBeforeNestedBlockParam: -#ObjCSpaceAfterProperty: -#ObjCSpaceBeforeProtocolList -PenaltyBreakAssignment: 1 -PenaltyBreakBeforeFirstCallParameter: 1 -PenaltyBreakComment: 1 -PenaltyBreakFirstLessLess: 1 -PenaltyBreakString: 1 -PenaltyBreakTemplateDeclaration: 1 -PenaltyExcessCharacter: 1 -PenaltyReturnTypeOnItsOwnLine: 1 -# Used as a fallback if alignment style can't be detected from code (DerivePointerAlignment: true) -PointerAlignment: Right -RawStringFormats: [] -ReflowComments: false -SortIncludes: false -SortUsingDeclarations: false -SpaceAfterCStyleCast: false -SpaceAfterLogicalNot: false -SpaceAfterTemplateKeyword: false -SpaceBeforeAssignmentOperators: true -SpaceBeforeCpp11BracedList: false -SpaceBeforeCtorInitializerColon: true -SpaceBeforeInheritanceColon: true -SpaceBeforeParens: ControlStatements -SpaceBeforeRangeBasedForLoopColon: true -SpaceBeforeSquareBrackets: false -SpaceInEmptyBlock: false -SpaceInEmptyParentheses: false -SpacesBeforeTrailingComments: 2 -SpacesInAngles: false -SpacesInCStyleCastParentheses: false -SpacesInConditionalStatement: false -SpacesInContainerLiterals: false -SpacesInParentheses: false -SpacesInSquareBrackets: false -Standard: Auto -StatementMacros: [] -TabWidth: 2 -TypenameMacros: [] -# Default to LF if line endings can't be detected from the content (DeriveLineEnding). -UseCRLF: false -UseTab: Never -WhitespaceSensitiveMacros: [] -``` +https://raw.githubusercontent.com/arduino/tooling-project-assets/main/other/clang-format-configuration/.clang-format ## Conclusion From 3200286b7aa452f13f3ef690dd214cb08006b454 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 26 Jul 2022 10:49:14 -0700 Subject: [PATCH 2/2] Move IDE 2.x configuration file link above supplemental link Arduino IDE 2.x allows the user to customize the output of the "Auto Format" feature via a configuration file. This system is documented in the "Customizing the Auto Formatter Feature" tutorial. Arduino's standard formatter configuration file is offered as part of the tutorial. Originally, the full YAML code of the standard configuration was included in the tutorial page itself. Since that consisted as a large block of cryptic code, it made sense to place it at the bottom of that section of the tutorial, after the section's prose content, following this structure: - Introduction - Supplemental note - Configuration code Since that time, the code content has been replaced by a link to the source file. After this change, the placement of this essential link (which is less visibly prominent in the page) makes less sense. The content will be easier to follow with the new structure: - Introduction - Configuration file link - Supplemental note --- .../tutorials/ide-v2-customize-auto-formatter/content.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md b/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md index 58dc6e34fd..b1d395f4ed 100644 --- a/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md +++ b/content/software/ide-v2/tutorials/ide-v2-customize-auto-formatter/content.md @@ -63,10 +63,10 @@ If you add a `.clang-format` configuration file to the root of a sketch, the Ard Here you can find the default formatting file used in the Arduino IDE 2.0. If you wish to customize how your auto formatting acts in the IDE then starting with this file is a good idea. -***Please note that the custom configuration file completely overrides the Arduino default configuration, rather than merging with it. Any configuration option you don't set in your custom file will be set to the ClangFormat default value.*** - https://raw.githubusercontent.com/arduino/tooling-project-assets/main/other/clang-format-configuration/.clang-format +***Please note that the custom configuration file completely overrides the Arduino default configuration, rather than merging with it. Any configuration option you don't set in your custom file will be set to the ClangFormat default value.*** + ## Conclusion In this tutorial we went through how to customize the behavior of the `CTRL + T` / `CMD + T` auto formatter command in the Arduino IDE 2.0. This tutorial also shows the different scopes that are available for the auto formatter configuration.