adjust docs to default: 'annotation'

Signed-off-by: Christoph Rueger <[email protected]>

docs/_chapters/230-manifest-annotations.md

@@ -28,9 +28,10 @@ Export-Package: com.acme;version="1.3.4"
 
 ### META-INF/services Annotations
 
-Some developers do not want to rely on the bnd/OSGi annotations. For this reason, it is possible to also apply the annotations to the files in the `META-INF/services`. These Service Loader files have the name of a Service Loader _service_ and contain the names of the implementation classes. One fully qualified name per line.
+Some developers do not want to rely on the additional dependency of bnd/OSGi annotations. For this reason, it is possible to also apply the annotations textually in comments to the files in the `META-INF/services`.
+This trick avoids a compile time dependency. These Service Loader files have the name of a Service Loader _service_ and contain the names of the implementation classes. One fully qualified name per line.
 
-The annotations can be applied in the comments. To make them more readable, it is possible to import the fully qualified name of the annotation.
+To make these annotations in the comments more readable, it is possible to import the fully qualified name of the annotation.
 ```
 META-INF/services/com.example.ServiceType:
 
@@ -42,9 +43,11 @@ META-INF/services/com.example.ServiceType:
 ```
 The processing is identical to the normal class based annotation processing. The `#class` macro will be set to the implementation class. The `#value` will be set in all cases to the service type unless overridden.
 
-This behavior can be controlled with the [-metainf-services](/instructions/metainf-services.html) instruction. Default is `auto` which automatically create `Provide-Capability` headers for services without textual annotations.
+This behavior can be controlled with the [-metainf-services](/instructions/metainf-services.html) instruction. Default is `annotation` which processes the textual annotations above, while the other convenience strategy `auto` automatically creates `Provide-Capability` headers for services without any textual annotations.
 
-Clearly using the class annotation is far superior:
+<hr />
+
+While the above is a compromise, clearly using the real class annotation is far superior:
 
 * Help from the IDE
 * Impossible to make typos

docs/_instructions/metainf-services.md

@@ -10,32 +10,33 @@ See the chapter about [META-INF/services Annotations](/chapters/230-manifest-ann
 
 This instruction can have the following values:
 
-- `auto` (default if not set): auto-register services without textual annotations. That means that bnd auto-generates a `aQute.bnd.annotation.spi.ServiceProvider` annotation without attributes 'under the hood' if an Implementation doesn't have one. This is useful if you just want to have bnd generate the `Provide-Capability` headers for `osgi.serviceloader`. Additionally 'auto' behaves like 'annotation'.
-- `annotation`: Scan files and only process textual annotations in comments of META-INF/services files.
-- `none`: disable processing of files in `META-INF/services`
+- `annotation` (default if not set): Scan META-INF/services files and only process those files which contain at least one textual annotations.
+- `auto`: The convenience strategy. Scans `META-INF/services` files and auto-registers implementations in services files which do not have a single textual annotation. The latter means that bnd behaves as if there was a `aQute.bnd.annotation.spi.ServiceProvider` annotation present on each implementation. This is useful if you just want to have bnd generate the `Provide-Capability` headers for `osgi.serviceloader`. Additionally `auto` behaves like `annotation` and would process all other files with textual annotations.
+- `none`: skip processing of files in `META-INF/services` completely
 
-## Example
+## Example of auto-registration
 
-Assume we want to wrap a non-OSGi library.
-Create `bnd.bnd` file and a library having a `META-INF/services` folder e.g. [groovy-3.0.22.jar](https://mvnrepository.com/artifact/org.codehaus.groovy/groovy/3.0.22) in a local `lib` folder.
+Assume we want to wrap a non-OSGi library containing `META-INF/services`.
+Create `bnd.bnd` file and put a library having a `META-INF/services` folder e.g. [groovy-3.0.22.jar](https://mvnrepository.com/artifact/org.codehaus.groovy/groovy/3.0.22) in a local `lib` folder.
 We will use `-includeresource: @lib/groovy-3.0.22.jar` to [unroll the jar](/instructions/includeresource.html#rolling). 
 
 ```
 # bnd.bnd
 -includeresource: @lib/groovy-3.0.22.jar
+-metainf-services: auto
 ```
 
-This uses the default `-metainf-services: auto` and creates a new jar with the following MANIFEST.MF headers from the `META-INF/services` folder:
+This creates a new jar with the following MANIFEST.MF headers from the `META-INF/services` folder:
 
 ```
 # MANIFEST.MF
 Provide-Capability                      osgi.service;objectClass:List<String>="org.codehaus.groovy.transform.ASTTransformation";effective:=active
                                         osgi.serviceloader;osgi.serviceloader="org.codehaus.groovy.transform.ASTTransformation";register:="groovy.grape.GrabAnnotationTransformation"
 Require-Capability                      osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))"
-                                        osgi.extender;filter:="(&(osgi.extender=osgi.serviceloader.registrar)(version>=1.0.0)(!(version>=2.0.0)))"
+                                        osgi.extender;filter:="(&(osgi.extender=osgi.serviceloader.registrar)(version>=1.0.0)(!(version>=2.0.0)))";resolution:=optional
 ```
 
-Because the default `-metainf-services: auto` is used, it instructs bnd to process textual annotations and also auto-generate a `@ServiceProvider` annotation annotation under the hood for services without annotations. 
-To prevent the latter (auto-generation) use the default `-metainf-services: annotation` or use `-metainf-services: none`.
+Because `-metainf-services: auto` is used, it instructs bnd to auto-generate a `@ServiceProvider` annotation under the hood for services without annotations. 
+To prevent the latter (auto-generation) use the default `-metainf-services: annotation` (to process only textual annotations) or use `-metainf-services: none` to skip processing of `META-INF/services` files completely.
 
 [source](https://github.com/bndtools/bnd/blob/master/biz.aQute.bndlib/src/aQute/bnd/osgi/metainf/MetaInfServiceParser.java)