Place attributes after phpdoc blocks.

Author: MagicPush

docs/changelog.md

@@ -150,7 +150,7 @@ This change log references the repository changes and releases, which respect [s
     1. Added `executeBuiltInSubcommandIfRequested()` method for built-in subcommands automatic execution;
        the method is utilized by `Parametizer::run()`.
 1. Added `CliRequestProcessor::parseSubcommandParameters()` protected method
-   to ease processing of the default subcommand switch value.
+   to ease processing of the default subcommand name (subcommand switch value).
 1. Added `CliRequestProcessor::$isForCompletion` readonly flag (settable in `__construct()`). The flag is used
    to stabilize completion output due to the default subcommand switch value.
 1. [Config.php](../src/Parametizer/Config/Config.php):

docs/development-notes.md

@@ -1,5 +1,7 @@
 # [CliToolkit](../README.md) -> Development notes
 
+Added here mainly for the library maintainers - not to forget decisions made to arguable cases.
+
 ## Contents
 
 - [PHPUnit](#phpunit)
@@ -10,6 +12,8 @@
     - [EnvironmentConfig load performance](#environmentconfig-load-performance)
     - [RegExp in subcommand name validation](#regexp-in-subcommand-name-validation)
 - [Throwing or ignoring exceptions default policy](#throwing-or-ignoring-exceptions-default-policy)
+- [Simplifying chain calls](#simplifying-chain-calls)
+    - [Parametizer::newConfig()](#parametizernewconfig)
 
 ## PHPUnit
 
@@ -147,3 +151,16 @@ The current policy:
     * Even if the library users do not read the documentation, at the first time they read a generated launcher script,
       they will know about a possibility to silence (or enable) exceptions. And then users decide if they prefer
       a zero-bug or production-safe setup.
+
+## Simplifying chain calls
+
+### `Parametizer::newConfig()`
+
+**Hypothesis**: `EnvironmentConfig` might be automatically created right in `Parametizer::newConfig()`, before
+internal calls in the stack reach `Config::__construct()`. Thus, `$throwOnException` parameter, needed (for now) only
+for `EnvironmentConfig` automatic creation, may be stripped off in the call stack - only `Parametizer::newConfig()`
+should keep this parameter, and `Config` then will require an env config instance only (no extra flag).
+
+**Decision**: this simplification should _not_ be implemented. From the development perspective, it changes
+almost nothing - almost no calls become easier in 95% of cases, if the methods' signatures are simplified.
+Because in 95% of cases `Parametizer::newConfig()` is called, not the inner methods along the stack.

docs/features-manual.md

@@ -5,7 +5,7 @@ Here are more detailed descriptions for different features you may find in the p
 ## Contents
 
 - [Classes or plain scripts](#classes-or-plain-scripts)
-    - [Class detection performance](#class-detection-performance)
+    - [Class detection performance](#class-detection-and-performance)
     - [Class scripts alternative launcher](#class-scripts-alternative-launcher)
 - [Parameter types](#parameter-types)
 - [Type casting from requests](#type-casting-from-requests)
@@ -79,8 +79,8 @@ aspects of developing a console script with this library:
     * _Class-based_: Just create a class-based script.
         * Generally, your launcher's detector will detect the new class automatically.
           Otherwise, update the detection rules in the launcher.
-        * In case of [caching detected class names](#class-detection-performance), you should re-create the cache file:
-          `php your-launcher.php script-launcher:clear-cache`
+        * In case of [caching detected class names](#class-detection-and-performance), you should re-create the cache
+          file: `php your-launcher.php script-launcher:clear-cache`
 * **Naming and grouping scripts**:
     * _Plain_: Placing scripts in different directories is your main option.
         * If you enable completion, then you may group your scripts by alias prefixes: generate completion scripts for
@@ -95,7 +95,7 @@ aspects of developing a console script with this library:
           detection rules to access a selected subset of scripts.
 </details>
 
-### Class detection performance
+### Class detection and performance
 
 `ScriptClassDetector` provides you with these ways (non-exclusive) to set detection rules:
 
@@ -106,7 +106,7 @@ aspects of developing a console script with this library:
     * User-friendly: pretty much - in trivial cases (all scripts are within a single directory or its subdirectories)
       it is enough to specify just a single directory.
     * Use case: in most cases this method covers your needs.
-1. `excludeDirectory()` allows you to filter out a directory that definitely should not be parsed. Obviously,
+2. `excludeDirectory()` allows you to filter out a directory that definitely should not be parsed. Obviously,
    this method works well only when paired with `searchDirectory()` method in the recursive mode.
     * Use case: the directory specified in `searchDirectory()` contains subdirectories that definitely do not contain
       console scripts. So you can improve the detection performance by filtering out non-relevant subpaths.
@@ -117,6 +117,12 @@ aspects of developing a console script with this library:
     * Use cases:
         * Cherry-picking particular scripts.
         * Improving detection performance (instead of pointing at a directory with thousands of files).
+4. Though not a part of `ScriptClassDetector` setup, there is a way to mark a class script ignored by all class
+   detectors: redefine `ScriptClassAbstract::isAvailableByDetector()` method for your particular script and make it
+   return `false` if you do not want that script to be detectable.
+
+   Do note however, that the detector's `scriptClassName()` method does _not_ consider
+   `ScriptClassAbstract::isAvailableByDetector()` and thus still allows to cherry-pick otherwise ignored scripts.
 
 Now consider an odd case. You have a large project (gigabytes / tens of thousands of files), but your console scripts
 are scattered throughout your whole project for some reason - for instance, each console script is placed close to