This is an automated email from the ASF dual-hosted git repository.
joshtynjala pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
commit 363639f3ea49c6ef993486d0dbb368980f4320bd
Author: Josh Tynjala <joshtynj...@bowlerhat.dev>
AuthorDate: Tue Sep 27 13:53:20 2022 -0700
Expand formatter and linter documentation, including asformat and aslint
-config.xml files
---
_data/toc.json | 6 +++++
formatter.md | 37 +++++++++++++++++++++++++-----
formatter/asformat-config-file.md | 47 +++++++++++++++++++++++++++++++++++++++
formatter/formatter-options.md | 2 +-
linter.md | 25 ++++++++++++++++-----
linter/aslint-config-file.md | 47 +++++++++++++++++++++++++++++++++++++++
linter/linter-options.md | 2 +-
7 files changed, 152 insertions(+), 14 deletions(-)
diff --git a/_data/toc.json b/_data/toc.json
index dd9d34b..86c76c0 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -249,6 +249,9 @@
{
"path": "formatter.md",
"children": [
+ {
+ "path": "formatter/asformat-config-file.md"
+ },
{
"path": "formatter/formatter-options.md"
}
@@ -257,6 +260,9 @@
{
"path": "linter.md",
"children": [
+ {
+ "path": "linter/aslint-config-file.md"
+ },
{
"path": "linter/linter-options.md"
}
diff --git a/formatter.md b/formatter.md
index 11ebeb4..305b1e4 100644
--- a/formatter.md
+++ b/formatter.md
@@ -30,14 +30,39 @@ Below are some pointers to help you get started with the
Royale formatter in var
### Command line
-The _bin_ directory of the Royale SDK should contain the **asformat** script
that will launch the formatter. Use `asformat --help` to see the [list of
available formatter options](formatter/formatter-options).
+The _bin_ directory of the Royale SDK should contain the **asformat** script
that will launch the formatter. Use `asformat --help` to see a [list of
available formatter options](formatter/formatter-options).
-### IDEs
+To use the default formatting options, simply pass in the path to a _.as_ or
_.mxml_ file as an argument.
-Consult your IDE documentation for how to use the Royale formatter.
+```sh
+asformat src/com/example/MyClass.as
+```
-## Formatter Options
+The formatted file contents will be printed to the standard output only, and
the original file will remain unmodified. To save the formatting changes, use
the `--write-files` option (or its shorter `-w` alias).
-The Royale formatter provides a number of command line options to customize
its use. You can find the list of formatter options here:
+```sh
+asformat --write-files src/com/example/MyClass.as
+```
-- [Formatter Options](formatter/formatter-options)
+To format multiple files, pass in a directory path. The formatter will search
this directory recursively for _.as_ and _.mxml_ files, and it will format
every one that it finds.
+
+```sh
+asformat --write-files src
+```
+
+To see which files were changed by the formatter, use the `--list-files`
option (or its shorter `-l` alias).
+
+```sh
+asformat --write-files --list-files src
+```
+
+### Editors and IDEs
+
+Consult your editor or IDE documentation to see whether it integrates the
Royale formatter or not. Many development environments have the ability to run
external command line programs, even if the Royale formatter is not directly
integrated.
+
+## Formatter configuration
+
+The Royale formatter provides a number of command line options to customize
its use. You can also save a list of the options for your project in a local
configuration file that will be detected automatically.
+
+- [List of formatter options](formatter/formatter-options)
+- [_asformat-config.xml_](formatter/asformat-config-file)
diff --git a/formatter/asformat-config-file.md
b/formatter/asformat-config-file.md
new file mode 100644
index 0000000..eb6180c
--- /dev/null
+++ b/formatter/asformat-config-file.md
@@ -0,0 +1,47 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: asformat-config.xml
+description: Configure asformat with an external asformat-config.xml file
+permalink: /formatter/asformat-config-file
+---
+
+# _asformat-config.xml_
+
+Configure the Royale formatter for a specific project
+
+If the current working directory contains an _asformat-config.xml_ file, the
[**asformat**](formatter/) tool will conveniently load this file automatically
to configure its options.
+
+The root of this file is an `<asformat-config>` element. To specify a
[formatter option](formatter/formatter-options), add it as a child element.
+
+```xml
+<asformat-config>
+ <collapse-empty-blocks>true</collapse-empty-blocks>
+ <max-preserve-new-lines>3</max-preserve-new-lines>
+ <semicolons>ignore</semicolons>
+</asformat-config>
+```
+
+For boolean option values, set the text inside the opening and closing tags to
`true` or `false`. For numeric option values, use the digits 0-9. For string
option values, enter the text as you would on the command line.
+
+## Disable _asformat-config.xml_
+
+To disable loading the _asformat-config.xml_ file, use the
`-skip-local-config-file` option.
+
+```sh
+asformat --skip-local-config-file --write-files src/com/example/MyClass.as
+```
\ No newline at end of file
diff --git a/formatter/formatter-options.md b/formatter/formatter-options.md
index fcd8293..118e96c 100644
--- a/formatter/formatter-options.md
+++ b/formatter/formatter-options.md
@@ -24,7 +24,7 @@ permalink: /formatter/formatter-options
List of all available formatter options
-This list may be generated by running `asformat -help advanced` in a terminal.
+The [**asformat**](formatter/) tool has a number of useful configuration
options. The list below is also available by running `asformat -help advanced`
in a terminal.
- `-collapse-empty-blocks` -- Determines if empty blocks containing no
statements will be collapsed to a single line, or if the closing curly brace
should still appear on a new line.
- `-help` `[keyword]` `[...]` -- Displays formatter usage instructions.
diff --git a/linter.md b/linter.md
index bafe92f..26b60ff 100644
--- a/linter.md
+++ b/linter.md
@@ -30,14 +30,27 @@ Below are some pointers to help you get started with the
Royale linter in variou
### Command line
-The _bin_ directory of the Royale SDK should contain the **aslint** script
that will launch the linter. Use `aslint --help` to see the [list of available
linter options](linter/linter-options).
+The _bin_ directory of the Royale SDK should contain the **aslint** script
that will launch the linter. Use `aslint --help` to see a [list of available
linter options](linter/linter-options).
-### IDEs
+To use the default linting options, simply pass in the path to a _.as_ or
_.mxml_ file as an argument.
-Consult your IDE documentation for how to use the Royale linter.
+```sh
+aslint src/com/example/MyClass.as
+```
-## Linter Options
+To lint multiple files, pass in a directory path. The linter will search this
directory recursively for _.as_ and _.mxml_ files, and it will lint every one
that it finds.
-The Royale linter provides a number of command line options to customize its
use. You can find the list of linter options here:
+```sh
+aslint src
+```
-- [Linter Options](linter/linter-options)
+### Editors and IDEs
+
+Consult your editor or IDE documentation to see whether it integrates the
Royale linter or not. Many development environments have the ability to run
external command line programs, even if the Royale linter is not directly
integrated.
+
+## Linter configuration
+
+The Royale linter provides a number of command line options to customize its
use. You can also save a list of the options for your project in a local
configuration file that will be detected automatically.
+
+- [List of linter options](linter/linter-options)
+- [_aslint-config.xml_](linter/aslint-config-file)
diff --git a/linter/aslint-config-file.md b/linter/aslint-config-file.md
new file mode 100644
index 0000000..fadb7cf
--- /dev/null
+++ b/linter/aslint-config-file.md
@@ -0,0 +1,47 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: aslint-config.xml
+description: Configure aslint with an external aslint-config.xml file
+permalink: /linter/aslint-config-file
+---
+
+# _aslint-config.xml_
+
+Configure the Royale linter for a specific project
+
+If the current working directory contains an _aslint-config.xml_ file, the
[**aslint**](/linter/) tool will conveniently load this file automatically to
configure its options.
+
+The root of this file is an `<aslint-config>` element. To specify a [linter
option](linter/linter-options), add it as a child element.
+
+```xml
+<aslint-config>
+ <max-params>5</max-params>
+ <no-dynamic-class>true</no-dynamic-class>
+ <line-comment-position>beside</line-comment-position>
+</aslint-config>
+```
+
+For boolean option values, set the text inside the opening and closing tags to
`true` or `false`. For numeric option values, use the digits 0-9. For string
option values, enter the text as you would on the command line.
+
+## Disable _aslint-config.xml_
+
+To disable loading the _aslint-config.xml_ file, use the
`-skip-local-config-file` option.
+
+```sh
+aslint --skip-local-config-file src/com/example/MyClass.as
+```
\ No newline at end of file
diff --git a/linter/linter-options.md b/linter/linter-options.md
index d6f51a2..949367d 100644
--- a/linter/linter-options.md
+++ b/linter/linter-options.md
@@ -24,7 +24,7 @@ permalink: /linter/linter-options
List of all available linter options
-This list may be generated by running `aslint -help advanced` in a terminal.
+The [**aslint**](linter/) tool has a number of useful configuration options.
The list below is also available by running `aslint -help advanced` in a
terminal.
- `-class-name` -- Ensures that class names follow a certain pattern.
- `-constant-name` -- Ensures that constant names follow a certain pattern.
