Updated Dart docs.

Author: simphotonics

README.md

@@ -13,13 +13,13 @@ and methods during the build process.
 
 The library [`merging_builder`][merging_builder] includes the following (synthetic input) builder classes:
 
-* [`MergingBuilder`][class-merging-builder] reads **several input files** and writes
-merged output to **one output file** to a custom location.
+* [`MergingBuilder`][class-merging-builder] reads *several input files* and writes
+merged output to *one output file* to a custom location.
 
 * [`StandaloneBuilder`][StandaloneBuilder] reads one or several input files and
-writes standalone files to a custom location. In this context, **standalone**
-means the output files may be written to a **custom folder** and
-not only the **extension** but the **name** of the output file can
+writes standalone files to a custom location. In this context, *standalone*
+means the output files may be written to a *custom folder* and
+not only the *extension* but the *name* of the output file can
 be configured (as opposed to using part files).
 
 
@@ -32,19 +32,19 @@ In the [example] project provided, the package defining a new
 builder is called `researcher_builder` and the package using this builder is called `researcher`.
 To set up a build system the following steps are required:
 
-### Builder Package Setup
+### 1. Builder Package Setup
 
 1. Get dependencies: Include [`merging_builder`][merging_builder], [`build`][build] as *dependencies* in the file `pubspec.yaml`. In the [example] mentioned here, the generator also requires the packages [`analyzer`][analyzer] and [`source_gen`][source_gen].
 
 2. Create a generator: Create a custom generator that extends [`MergingGenerator`][MergingGenerator]. In [example] `generateItemForAnnotatedElement` reads a list of strings while `generateMergedContent` merges the data and generates output that is written to [researchers.dart].
 
 3. Create a builder: Create an instance of [`MergingBuilder`][MergingBuilder]. Following the example of [`source_gen`][source_gen], builders are typically placed in a file called: `builder.dart` located in the `lib` folder of the builder package.
    * Input sources may be specified using wildcard characters supported by [`Glob`][Glob].
-   * The builder definition includes the default values of the *options* `input_files`, `output_file`, `header`, `footer`, and `sort_assets`. These options can be overwritten by the user of the builder by specifying them explicitly in the file `build.yaml`  located  in the package `researcher` (see step 5).
+   * The builder definition includes the default values of the *options* `input_files`, `output_file`, `header`, `footer`, and `sort_assets`. These options can be overwritten by the user of the builder by specifying them explicitly in the file `build.yaml`  located  in the package `researcher` (see step 1 in section [User Package Setup](#1-builder-package-setup)).
 
 4. Add a builder configuration:  The build extensions for
 [`MergingBuilder`][MergingBuilder] must be specified using the notation
-available for **synthetic input**. For example, `"$lib$"` indicates that the
+available for *synthetic input*. For example, `"$lib$"` indicates that the
 input files are located in the folder `lib` or a subfolder thereof.
     ```Yaml
     builders:
@@ -62,15 +62,16 @@ input files are located in the folder `lib` or a subfolder thereof.
         build_to: source
     ```
 
-### User Package Setup
+### 2. User Package Setup
 
-The following steps are performed in the package that is using the custom builder.
+The following steps are performed in the package that is using the custom builder:
 
-1. Add dependencies: Add the builder package and [`build_runner`][build_runner] as *dev_dependencies* in the file `pubspec.yaml`.
+1. Add dependencies: Add the custom builder package and
+[`build_runner`][build_runner] as a *dev_dependencies* in the file `pubspec.yaml`.
 
-2. Builder configuration: Add the builder to the list of known builders and configure
-the available options.
-The sample `build.yaml` file is shown below.
+2. Builder configuration: Add the builder to the list of known builders
+and configure the available options (thus overwriting the default values).
+A sample `build.yaml` file is shown below.
 
     ```Yaml
      targets:
@@ -109,7 +110,7 @@ use *synthetic input*.
 
 ### Merging Builder
 
-[`MergingBuilder`][MergingBuilder] reads **several input files** and writes merged output to **one output file**.
+[`MergingBuilder`][MergingBuilder] reads *several input files* and writes merged output to *one output file*.
 The builder provides the option to sort the input files in reverse topological order.
 If the input file `a.dart` includes file `b.dart` then `a.dart` will be listed *after* `b.dart`. This option may be useful when
 generating code that needs to list variables or call functions in order of dependence.
@@ -134,7 +135,8 @@ wild-card notation supported by [`Glob`][Glob].
 Output files are specified by using the custom symbol
 `(*)`. For example, the output path `output\assistant_(*).dart` is interpreted such that `(*)` is replaced with the input file name (excluding the file extension). For more details, see the file [`example\researcher_builder\builder.dart`][builder.dart].
 
-Limitations: For builders extending [`StandaloneBuilder`][StandaloneBuilder] it is recommended to initiate the build command (see point 7 in the next section) from the root directory of the package the build is applied to.
+Limitations: For builders extending [`StandaloneBuilder`][StandaloneBuilder] it is recommended to initiate the build command
+from the root directory of the package the build is applied to.
 ## Examples
 
 For further information on how to use [`MergingBuilder`][MergingBuilder] see [example].
@@ -173,22 +175,16 @@ Please file feature requests and bugs at the [issue tracker].
 
 [Glob]: https://pub.dev/packages/glob
 
-[LibDir]: https://pub.dev/documentation/merging_builder/latest/merging_builder/LibDir-class.html
-
 [MergingBuilder]: https://pub.dev/documentation/merging_builder/latest/merging_builder/MergingBuilder-class.html
 
 [merging_builder]: https://pub.dev/packages/merging_builder
 
 [MergingGenerator]: https://pub.dev/documentation/merging_builder/latest/merging_builder/MergingGenerator-class.html
 
-[PackageDir]: https://pub.dev/documentation/merging_builder/latest/merging_builder/PackageDir-class.html
-
 [researchers.dart]: https://github.com/simphotonics/merging_builder_example/blob/main/researcher/lib/output/researchers.dart
 
 [source_gen]: https://pub.dev/packages/source_gen
 
 [source_gen_test]: https://pub.dev/packages/source_gen_test
 
 [StandaloneBuilder]: https://pub.dev/documentation/merging_builder/latest/merging_builder/StandaloneBuilder-class.html
-
-[Writing a Builder using a synthetic input]: https://github.com/dart-lang/build/blob/master/docs/writing_an_aggregate_builder.md#writing-the-builder-using-a-synthetic-input

example/README.md

@@ -4,11 +4,12 @@
 
 ## Introduction
 
-The package [`merging_builder`][merging_builder] provides a Dart builder that reads **several input files** and writes the merged output to **one output file**.
+The package [`merging_builder`][merging_builder] provides a Dart builder that reads *several input files* and writes the merged output to *one output file*.
 
-The [example] presented here contains two packages. The package [`researcher_builder`][researcher_builder] depends on [`merging_builder`][merging_builder] in order to define the builder [`add_names_builder`][add_names_builder] and the merging generator [`add_names_generator`][add_names_generator].
+The projec provided as an [example] contains two packages:
+* The package [`researcher_builder`][researcher_builder] depends on [`merging_builder`][merging_builder] in order to define the builder [`add_names_builder`][add_names_builder] and the merging generator [`add_names_generator`][add_names_generator].
 
-The package [`researcher`][researcher] depends on [`researcher_builder`][researcher_builder], specified as a *dev_dependency*, in order to access the builder [`add_names_builder`][add_names_builder] during the build process.
+* The package [`researcher`][researcher] depends on [`researcher_builder`][researcher_builder], specified as a *dev_dependency*, in order to access the builder [`add_names_builder`][add_names_builder] during the build process.
 
 ## Build Setup
 

images/merging_builder.svg

@@ -1,5 +1,5 @@
 /// Typedef of a function that can be provided to
-/// [MergingBuilder] and [StandAloneBuilder]
+/// `MergingBuilder` and `StandAloneBuilder`
 /// constructors in the form of the parameter `formatter`.
 /// * The function is used to format the builder output before it
 /// is written to a file.