Update api region documentation
diff --git a/README.md b/README.md
index 188c987..a33cf43 100644
--- a/README.md
+++ b/README.md
@@ -2,22 +2,17 @@
[](https://builds.apache.org/job/Sling/job/sling-org-apache-sling-feature-extension-apiregions/job/master) [](https://builds.apache.org/job/Sling/job/sling-org-apache-sling-feature-extension-apiregions/job/master/test_results_analyzer/) [](https://www.apache.org/licenses/LICENSE-2.0) [](https://github.com/apache/sling-aggregator/blob/master/docs/groups/feature.md)
-# Apache Sling API Regions extension
+# Apache Sling API Regions Extension for the Feature Model
This component contains extensions relating to the API Regions component.
Read the documentation about [API Regions](docs/api-regions.md) for more information.
-The following extensions are registered via the ServiceLoader mechanism:
-
-## `org.apache.sling.feature.builder.MergeHandler`
-Merge handlers are called when features are merged during the aggregation process.
-
-`APIRegionMergeHandler` - This handler knows how to merge API Regions extensions
-
-# Feature Model Analysers
+## Feature Model Analysers
This component also contains Feature Model Analysers they are contributed through the Service Loader mechanism to the set of Analysers.
+Documentation can be found here: https://github.com/apache/sling-org-apache-sling-feature-analyser . These can be run as part of the 'analyse-features' goal with the [slingfeature-maven-plugin](https://github.com/apache/sling-slingfeature-maven-plugin#analyse-features-analyse-features).
+
These analysers relate to API Region definitions in Feature Models.
* `api-regions`: This analyser ensures that packages listed as exports in API-Regions sections are actually exported by a bundle that's part of the feature.
@@ -52,6 +47,16 @@
* `warningPackages`: if packages listed here are found to overlap, a warning instead of an error is reported. Supports either literal package names (e.g. `javax.servlet`) or wildcards with an asterisk at the end (e.g. `javax.*`).
* `ignoredPackages`: packages listed here are completely ignored in the analysis. Supports literal package names or wildcards with an asterisk at the end.
+## Extensions
+
+The following extensions are registered via the ServiceLoader mechanism:
+
+## `org.apache.sling.feature.builder.MergeHandler`
+Merge handlers are called when features are merged during the aggregation process.
+
+`APIRegionMergeHandler` - This handler knows how to merge API Regions extensions
+
+
# Additional Extensions
The following extensions are also implemented by this component and made available through the Service Loader mechanism:
diff --git a/docs/api-regions.md b/docs/api-regions.md
index 412d8ea..e68d9e6 100644
--- a/docs/api-regions.md
+++ b/docs/api-regions.md
@@ -1,10 +1,10 @@
-# API Regions
+# API Regions for the Feature Model
If you're assembling a platform (in contrast to a final application) out of several features and provide this platform for customers to build their application on top of, additional control of the API provided by the platform is needed. The bundles within the features provide all kinds of APIs but you might not want to expose all of these as extension points. You would rather want to use some of them internally within either a single feature or share within your platform features.
-# Visibility of API
+## Visibility of API
-A feature exports some api, however there are different types of clients of the API:
+A feature exports some API, however there are two different types of clients of the API:
* Bundles shipped as part of the platform
* Application bundles using the platform
@@ -13,7 +13,7 @@
Without any further information, API is globally visible by default. However, for platform features we want the opposite as we want to ensure that newly added API is not visible to all bundles by default.
-A feature can have an additional extension JSON named api-regions. The following example exposes some packages to the global region and an additional package to the platform region. Exports declared earlier in the api-regions array also apply to later elements in the array, so the `platform` region also contains all exports declared for the `global` region.
+A feature can have an additional extension of type JSON named `api-region`. The following example exposes some packages to the global region and an additional package to the platform region. Exports declared earlier in the api-regions array also apply to later elements in the array, so the `platform` region also contains all exports declared for the `global` region.
Note that the `global` region is a predefined region that exports the listed packages to everyone. Other region names can be chosen freely. Packages listed in these other regions are only exposed to bundles in features that are in the same region.
@@ -38,8 +38,7 @@
}
]
-Of course the above mentioned packages need to be exported by some bundle within the feature.
-By exporting packages to a given region, a feature automatically also sees all packages available to that region (or regions).
+Of course the above mentioned packages need to be exported by some bundle within the feature. By exporting packages to a given region, a feature automatically also sees all packages available to that region (or regions).
A feature can also just consume packages from a region, without having to export any packages to it. This can be done by exporting an empty list of packages. For example:
@@ -60,7 +59,3 @@
"exports": []
}
]
-
-To support feature inheritance, [this module](../README.md) containing an extension handler must be registered which will merge the extension.
-
-A number of API region related analysers/validators exist. Documentation can be found here: https://github.com/apache/sling-org-apache-sling-feature-analyser . These can be run as part of the 'analyse-features' goal with the [slingfeature-maven-plugin](https://github.com/apache/sling-slingfeature-maven-plugin#analyse-features-analyse-features).
