More AsciiDoc improvements, mostly about code formatting (WIP)

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

5 files changed, 91 insertions, 103 deletions

diff --git a/docs/adk15ProgGuideDB/annotations.adoc b/docs/adk15ProgGuideDB/annotations.adoc
index e0e56fc71..5fcf74608 100644
--- a/docs/adk15ProgGuideDB/annotations.adoc
+++ b/docs/adk15ProgGuideDB/annotations.adoc
@@ -61,17 +61,13 @@ Annotations can have one of three retention policies:
 
 Source-file retention::
   Annotations with source-file retention are read by the compiler during
-  the compilation process, but are not rendered in the generated
-  `.class` files.
+  the compilation process, but are not rendered in the generated `.class` files.
 Class-file retention::
   This is the default retention policy. Annotations with class-file
-  retention are read by the compiler and also retained in the generated
-  `
-                          .class` files.
+  retention are read by the compiler and also retained in the generated `.class` files.
 Runtime retention::
   Annotations with runtime retention are read by the compiler, retained
-  in the generated `
-                          .class` files, and also made available at
+  in the generated `.class` files, and also made available at
   runtime.
 
 Local variable annotations are not retained in class files (or at
@@ -201,7 +197,6 @@ public aspect AnAspect {
 
   pointcut anInterfaceOperation() : execution(* AnInterface.*(..));
 
-
   @SuppressAjWarnings // may not match if there are no implementers of the interface...
   before() : anInterfaceOperation() {
      // do something...
@@ -229,8 +224,8 @@ etc.), an annotation pattern can be used to match against the set of
 annotations on the annotated element.An annotation pattern element has
 one of two basic forms:
 
-* @<qualified-name>, for example, @Foo, or @org.xyz.Foo.
-* @(<type-pattern>), for example, @(org.xyz..*), or @(Foo || Boo)
+* `@<qualified-name>`, for example, `@Foo`, or `@org.xyz.Foo`.
+* `@(<type-pattern>)`, for example, `@(org.xyz..*)`, or `@(Foo || Boo)`
 
 These simple elements may be negated using `!`, and combined by simple
 concatentation. The pattern `@Foo @Boo` matches an annotated element
@@ -239,21 +234,21 @@ that has both an annotation of type `Foo` and an annotation of type
 
 Some examples of annotation patterns follow:
 
-@Immutable::
+`@Immutable`::
   Matches any annotated element which has an annotation of type
   `Immutable`.
-!@Persistent::
+`!@Persistent`::
   Matches any annotated element which does not have an annotation of
   type `Persistent`.
-@Foo @Goo::
+`@Foo @Goo`::
   Matches any annotated element which has both an annotation of type
   `Foo` and an annotation of type `Goo`.
-@(Foo || Goo)::
+`@(Foo || Goo)`::
   Matches any annotated element which has either an annotation of a type
   matching the type pattern `(Foo || Goo)`. In other words, an annotated
   element with either an annotation of type `Foo` or an annotation of
   type `Goo` (or both). (The parenthesis are required in this example).
-@(org.xyz..*)::
+`@(org.xyz..*)`::
   Matches any annotated element which has either an annotation of a type
   matching the type pattern `(org.xyz..*)`. In other words, an annotated
   element with an annotation that is declared in the org.xyz package or
@@ -299,25 +294,25 @@ OptionalParensTypePattern := AnnotationPattern? TypePattern
 The following examples illustrate the use of annotations in type
 patterns:
 
-(@Immutable *)::
+`(@Immutable *)`::
   Matches any type with an `@Immutable` annotation.
-(!@Immutable *)::
+`(!@Immutable *)`::
   Matches any type which does not have an `@Immutable` annotation.
-(@Immutable (org.xyz.* || org.abc.*))::
+`(@Immutable (org.xyz.* || org.abc.*))`::
   Matches any type in the `org.xyz` or `org.abc` packages with the
   `@Immutable` annotation.
-((@Immutable Foo+) || Goo)::
+`((@Immutable Foo+) || Goo)`::
   Matches a type `Foo` or any of its subtypes, which have the
   `@Immutable` annotation, or a type `Goo`.
-((@(Immutable || NonPersistent) org.xyz..*)::
+`((@(Immutable || NonPersistent) org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has either the `@Immutable` annotation or the `@NonPersistent`
   annotation.
-(@Immutable @NonPersistent org.xyz..*)::
+`(@Immutable @NonPersistent org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has both an `@Immutable` annotation and an `@NonPersistent`
   annotation.
-(@(@Inherited *) org.xyz..*)::
+`(@(@Inherited *) org.xyz..*)`::
   Matches any type in a package beginning with the prefix `org.xyz`,
   which has an inheritable annotation. The annotation pattern
   `@(@Inherited *)` matches any annotation of a type matching the type
@@ -352,20 +347,20 @@ SimpleNamePattern := JavaIdentifierChar+ ('*' SimpleNamePattern)?
 If present, the `AnnotationPattern` restricts matches to fields with
 annotations that match the pattern. For example:
 
-@SensitiveData * *::
+`@SensitiveData * *`::
   Matches a field of any type and any name, that has an annotation of
   type `@SensitiveData`
-@SensitiveData List org.xyz..*.*::
+`@SensitiveData List org.xyz..*.*`::
   Matches a member field of a type in a package with prefix `org.xzy`,
   where the field is of type `List`, and has an annotation of type
   `@SensitiveData`
-(@SensitiveData *) org.xyz..*.*::
+`(@SensitiveData *) org.xyz..*.*`::
   Matches a member field of a type in a package with prefix `org.xzy`,
   where the field is of a type which has a `@SensitiveData` annotation.
-@Foo (@Goo *) (@Hoo *).*::
+`@Foo (@Goo *) (@Hoo *).*`::
   Matches a field with an annotation `@Foo`, of a type with an
   annotation `@Goo`, declared in a type with annotation `@Hoo`.
-@Persisted @Classified * *::
+`@Persisted @Classified * *`::
   Matches a field with an annotation `@Persisted` and an annotation
   `@Classified`.
 
@@ -418,37 +413,37 @@ The optional `AnnotationPattern` at the beginning of a method or
 constructor pattern restricts matches to methods/constructors with
 annotations that match the pattern. For example:
 
-@Oneway * *(..)::
+`@Oneway * *(..)`::
   Matches a method with any return type and any name, that has an
   annotation of type `@Oneway`.
-@Transaction * (@Persistent org.xyz..*).*(..)::
+`@Transaction * (@Persistent org.xyz..*).*(..)`::
   Matches a method with the `@Transaction` annotation, declared in a
   type with the `@Persistent` annotation, and in a package beginning
   with the `org.xyz` prefix.
-* *.*(@Immutable *,..)::
+`* *.*(@Immutable *,..)`::
   Matches any method taking at least one parameter, where the parameter
   type has an annotation `@Immutable`.
 
 ==== Example Pointcuts
 
-within(@Secure *)::
+`within(@Secure *)`::
   Matches any join point where the code executing is declared in a type
   with an `@Secure` annotation. The format of the `within` pointcut
   designator in AspectJ 5 is
   `'within' '(' OptionalParensTypePattern ')'`.
-staticinitialization(@Persistent *)::
+`staticinitialization(@Persistent *)`::
   Matches the staticinitialization join point of any type with the
   `@Persistent` annotation. The format of the `staticinitialization`
   pointcut designator in AspectJ 5 is
   `'staticinitialization' '(' OptionalParensTypePattern ')'`.
-call(@Oneway * *(..))::
+`call(@Oneway * *(..))`::
   Matches a call to a method with a `@Oneway` annotation.
-execution(public (@Immutable *) org.xyz..*.*(..))::
+`execution(public (@Immutable *) org.xyz..*.*(..))`::
   The execution of any public method in a package with prefix `org.xyz`,
   where the method returns an immutable result.
-set(@Cachable * *)::
+`set(@Cachable * *)`::
   Matches the set of any cachable field.
-handler(!@Catastrophic *)::
+`handler(!@Catastrophic *)`::
   Matches the handler join point for the handling of any exception that
   is not `Catastrophic`. The format of the `handler` pointcut designator
   in AspectJ 5 is `'handler' '(' OptionalParensTypePattern ')'`.
@@ -501,10 +496,10 @@ name are analogous to their counterparts that take a single type name.
 They match at join points where the object bound to `this` (or `target`,
 respectively) has an annotation of the specified type. For example:
 
-@this(Foo)::
+`@this(Foo)`::
   Matches any join point where the object currently bound to 'this' has
   an annotation of type `Foo`.
-call(* *(..)) && @target(Classified)::
+`call(* *(..)) && @target(Classified)`::
   Matches a call to any object where the target of the call has a
   `@Classified` annotation.
 
@@ -573,10 +568,10 @@ AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'
 
 Some examples of using these designators follow:
 
-@within(Foo)::
+`@within(Foo)`::
   Matches any join point where the executing code is defined within a
   type which has an annotation of type `Foo`.
-pointcut insideCriticalMethod(Critical c) : @withincode(c);::
+`pointcut insideCriticalMethod(Critical c) : @withincode(c);`::
   Matches any join point where the executing code is defined in a method
   or constructor which has an annotation of type `@Critical`, and
   exposes the value of the annotation in the parameter `c`.
@@ -777,10 +772,10 @@ specification, it is now possible to match types based on the presence
 of annotations _with either class-file or runtime retention_. For
 example:
 
-declare parents : (@Secured *) implements SecuredObject;::
+`declare parents : (@Secured *) implements SecuredObject;`::
   All types with the `@Secured` annotation implement the `SecuredObject`
   inteface.
-declare parents : (@Secured BankAccount+) implements SecuredObject;::
+`declare parents : (@Secured BankAccount+) implements SecuredObject;`::
   The subset of types drawn from the `BankAccount` type and any subtype
   of `BankAccount`, where the `@Secured` annotation is present,
   implement the `SecuredObject` interface.
@@ -804,7 +799,7 @@ declare precedence : TypePatList;
 AspectJ 5 allows the type patterns in the list to include annotation
 information as part of the pattern specification. For example:
 
-declare precedence : (@Security *),*;::
+`declare precedence : (@Security *),*;`::
   All aspects with the `@Security` annotation take precedence over any
   other aspects in the system. (Or, more informally, all
   security-related aspects take precedence).
@@ -843,18 +838,18 @@ ElementPattern := TypePattern |
 
 The following examples illustrate the use of `declare annotation`.
 
-declare @type : org.xyz.model..* : @BusinessDomain ;::
+`declare @type : org.xyz.model..* : @BusinessDomain ;`::
   All types defined in a package with the prefix `org.xyz.model` have
   the `@BusinessDomain` annotation.
 declare @method : public * BankAccount+.*(..) :
-@Secured(role="supervisor")::
+`@Secured(role="supervisor")`::
   All public methods in `BankAccount` and its subtypes have the
   annotation `@Secured(role="supervisor")`.
 declare @constructor : BankAccount+.new(..) :
-@Secured(role="supervisor")::
+`@Secured(role="supervisor")`::
   All constructors in `BankAccount` and its subtypes have the annotation
   `@Secured(role="supervisor")`.
-declare @field : * DAO+.* : @Persisted;::
+`declare @field : * DAO+.* : @Persisted;`::
   All fields defined in `DAO` or its subtypes have the `@Persisted`
   annotation.
 
diff --git a/docs/adk15ProgGuideDB/covariance.adoc b/docs/adk15ProgGuideDB/covariance.adoc
index 49dda35ee..793b134f2 100644
--- a/docs/adk15ProgGuideDB/covariance.adoc
+++ b/docs/adk15ProgGuideDB/covariance.adoc
@@ -52,31 +52,31 @@ B B.whoAreYou()
 
 Following the join point matching rules given in xref:joinpointsignatures.adoc#jpsigs[Join Point Signatures].
 
-call(* whoAreYou())::
+`call(* whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(* A.whoAreYou())::
+`call(* A.whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(A whoAreYou())::
+`call(A whoAreYou())`::
   Matches both calls, (since each call join point has at least one
   matching signature).
-call(A B.whoAreYou())::
+`call(A B.whoAreYou())`::
   Does not match anything - neither of the call join points has a
   signature matched by this pattern. A lint warning is given for the
   call `a.whoAreYou()` ("does not match because declaring type is A, if
   match required use target(B)").
-call(A+ B.whoAreYou())::
+`call(A+ B.whoAreYou())`::
   Matches the call to `b.whoAreYou()` since the signature pattern
   matches the signature `B B.whoAreYou()`. A lint warning is given for
   the call `a.whoAreYou()` ("does not match because declaring type is A,
   if match required use target(B)").
-call(B A.whoAreYou())::
+`call(B A.whoAreYou())`::
   Does not match anything since neither join point has a signature
   matched by this pattern.
-call(B whoAreYou())::
+`call(B whoAreYou())`::
   Matches the call to `b.whoAreYou()` only.
-call(B B.whoAreYou())::
+`call(B B.whoAreYou())`::
   Matches the call to `b.whoAreYou()` only.
 
 The rule for signature matching at call and execution join points is
diff --git a/docs/adk15ProgGuideDB/generics.adoc b/docs/adk15ProgGuideDB/generics.adoc
index cd9c101b1..7d1c41a57 100644
--- a/docs/adk15ProgGuideDB/generics.adoc
+++ b/docs/adk15ProgGuideDB/generics.adoc
@@ -41,18 +41,18 @@ addition to simple type parameter names, type parameter declarations can
 also constrain the set of types allowed by using the `extends` keyword.
 Some examples follow:
 
-class Foo<T> \{...}::
+`class Foo<T> {...}`::
   A class `Foo` with one type parameter, `T`.
-class Foo<T,S> \{...}::
+`class Foo<T,S> {...}`::
   A class `Foo` with two type parameters, `T` and `S`.
-class Foo<T extends Number> \{...}::
+`class Foo<T extends Number> {...}`::
   A class `Foo` with one type parameter `T`, where `T` must be
   instantiated as the type `Number` or a subtype of `Number`.
-class Foo<T, S extends T> \{...}::
+`class Foo<T, S extends T> {...}`::
   A class `Foo` with two type parameters, `T` and `S`. `Foo` must be
   instantiated with a type `S` that is a subtype of the type specified
   for parameter `T`.
-class Foo<T extends Number & Comparable> \{...}::
+`class Foo<T extends Number & Comparable> {...}`::
   A class `Foo` with one type parameter, `T`. `Foo` must be instantiated
   with a type that is a subtype of `Number` and that implements
   `Comparable`.
@@ -91,13 +91,13 @@ stands for "some type". The `extends` and `super` keywords may be used
 in conjunction with the wildcard to provide upper and lower bounds on
 the types that may satisfy the type constraints. For example:
 
-List<?>::
+`List<?>`::
   A list containing elements of some type, the type of the elements in
   the list is unknown.
-List<? extends Number>::
+`List<? extends Number>`::
   A list containing elements of some type that extends Number, the exact
   type of the elements in the list is unknown.
-List<? super Double>::
+`List<? super Double>`::
   A list containing elements of some type that is a super-type of
   Double, the exact type of the elements in the list is unknown.
 
@@ -105,24 +105,24 @@ A generic type may be extended as any other type. Given a generic type
 `Foo<T>` then a subtype `Goo` may be declared in one of the following
 ways:
 
-class Goo extends Foo::
+`class Goo extends Foo`::
   Here `Foo` is used as a raw type, and the appropriate warning messages
   will be issued by the compiler on attempting to invoke methods in
   `Foo`.
-class Goo<E> extends Foo::
+`class Goo<E> extends Foo`::
   `Goo` is a generic type, but the super-type `Foo` is used as a raw
   type and the appropriate warning messages will be issued by the
   compiler on attempting to invoke methods defined by `Foo`.
-class Goo<E> extends Foo<E>::
+`class Goo<E> extends Foo<E>`::
   This is the most usual form. `Goo` is a generic type with one
   parameter that extends the generic type `Foo` with that same
   parameter. So `Goo<String<` is a subclass of `Foo<String>`.
-class Goo<E,F> extends Foo<E>::
+`class Goo<E,F> extends Foo<E>`::
   `Goo` is a generic type with two parameters that extends the generic
   type `Foo` with the first type parameter of `Goo` being used to
   parameterize `Foo`. So `Goo<String,Integer<` is a subclass of
   `Foo<String>`.
-class Goo extends Foo<String>::
+`class Goo extends Foo<String>`::
   `Goo` is a type that extends the parameterized type `Foo<String>`.
 
 A generic type may implement one or more generic interfaces, following
@@ -416,14 +416,14 @@ class C {
 }
 ....
 
-execution(* C.*(List))::
+`execution(* C.*(List))`::
   Matches an execution join point for any of the three methods.
-execution(* C.*(List<? extends Number>))::
+`execution(* C.*(List<? extends Number>))`::
   matches only the execution of `foo`, and _not_ the execution of `goo`
   since `List<? extends Number>` and `List<Double>` are distinct types.
-execution(* C.*(List<?>))::
+`execution(* C.*(List<?>))`::
   matches only the execution of `bar`.
-execution(* C.*(List<? extends Object+>))::
+`execution(* C.*(List<? extends Object+>))`::
   matches both the execution of `foo` and the execution of `bar` since
   the upper bound of `List<?>` is implicitly `Object`.
 
@@ -507,11 +507,11 @@ public class C {
 }
 ....
 
-args(List)::
+`args(List)`::
   will match an execution or call join point for any of these methods
-args(List<String>)::
+`args(List<String>)`::
   will match an execution or call join point for `foo`.
-args(List<Double>)::
+`args(List<Double>)`::
   matches an execution or call join point for `bar`, and _may_ match at
   an execution or call join point for `goo` since it is legitimate to
   pass an object of type `List<Double>` to a method expecting a
@@ -761,17 +761,16 @@ members on generic types. For generic methods, the syntax is exactly as
 for a regular method declaration, with the addition of the target type
 specification:
 
-<T extends Number> T Utils.max(T first, T second) \{...}::
+`<T extends Number> T Utils.max(T first, T second) {...}`::
   Declares a generic instance method `max` on the class `Util`. The
   `max` method takes two arguments, `first` and `second` which must both
   be of the same type (and that type must be Number or a subtype of
   Number) and returns an instance of that type.
-static <E> E Utils.first(List<E> elements) \{...}::
+`static <E> E Utils.first(List<E> elements) {...}`::
   Declares a static generic method `first` on the class `Util`. The
   `first` method takes a list of elements of some type, and returns an
   instance of that type.
-<T> Sorter.new(List<T> elements,Comparator<? super T> comparator)
-\{...}::
+<T> Sorter.new(List<T> elements,Comparator<? super T> comparator) `{...}`::
   Declares a constructor on the class `Sorter`. The constructor takes a
   list of elements of some type, and a comparator that can compare
   instances of the element type.
@@ -783,17 +782,17 @@ match the number of type parameters in the generic type declaration.
 Type parameter _names_ do not have to match. For example, given the
 generic type `Foo<T,S extends Number>` then:
 
-String Foo.getName() \{...}::
+`String Foo.getName() {...}`::
   Declares a `getName` method on behalf of the type `Foo`. It is not
   possible to refer to the type parameters of Foo in such a declaration.
-public R Foo<Q, R>.getMagnitude() \{...}::
+`public R Foo<Q, R>.getMagnitude() {...}`::
   Declares a method `getMagnitude` on the generic class `Foo`. The
   method returns an instance of the type substituted for the second type
   parameter in an invocation of `Foo` If `Foo` is declared as
   `Foo<T,N extends Number> {...}` then this inter-type declaration is
   equivalent to the declaration of a method `public N getMagnitude()`
   within the body of `Foo`.
-R Foo<Q, R extends Number>.getMagnitude() \{...}::
+`R Foo<Q, R extends Number>.getMagnitude() {...}`::
   Results in a compilation error since a bounds specification is not
   allowed in this form of an inter-type declaration (the bounds are
   determined from the declaration of the target type).
@@ -814,7 +813,7 @@ would be well-formed in accordance with Java's sub-typing rules).
 Generic types may also be used as the target type of a `declare parents`
 statement.
 
-declare parents: Foo implements List<String>::
+`declare parents: Foo implements List<String>`::
   The `Foo` type implements the `List<String>` interface. If `Foo`
   already implements some other parameterization of the `List` interface
   (for example, `List<Integer>` then a compilation error will result
@@ -840,25 +839,22 @@ Given the aspect declaration:
 [source, java]
 ....
 public abstract aspect ParentChildRelationship<P,C> {
-    ...
+    // ...
 }
 ....
 
 then
 
-public aspect FilesInFolders extends
-ParentChildRelationship<Folder,File> \{...::
+`public aspect FilesInFolders extends ParentChildRelationship<Folder,File> {...`::
   declares a concrete sub-aspect, `FilesInFolders` which extends the
   parameterized abstract aspect `ParentChildRelationship<Folder,File>`.
-public aspect FilesInFolders extends ParentChildRelationship \{...::
+`public aspect FilesInFolders extends ParentChildRelationship {...`::
   results in a compilation error since the `ParentChildRelationship`
   aspect must be fully parameterized.
-public aspect ThingsInFolders<T> extends
-ParentChildRelationship<Folder,T>::
+`public aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T>`::
   results in a compilation error since concrete aspects may not have
   type parameters.
-public abstract aspect ThingsInFolders<T> extends
-ParentChildRelationship<Folder,T>::
+`public abstract aspect ThingsInFolders<T> extends ParentChildRelationship<Folder,T>`::
   declares a sub-aspect of `ParentChildRelationship` in which `Folder`
   plays the role of parent (is bound to the type variable `P`).
 
diff --git a/docs/adk15ProgGuideDB/joinpointsignatures.adoc b/docs/adk15ProgGuideDB/joinpointsignatures.adoc
index 07df75f92..1ed54baa8 100644
--- a/docs/adk15ProgGuideDB/joinpointsignatures.adoc
+++ b/docs/adk15ProgGuideDB/joinpointsignatures.adoc
@@ -10,16 +10,13 @@ annotations, generics, covariance, varargs, and autoboxing.
 === Join Point Matching
 
 AspectJ supports 11 different kinds of join points. These are the
-`method call, method execution, constructor call,
-        constructor execution, field get, field set, pre-initialization,
-        initialization, static initialization, handler,` and
-`advice execution` join points.
+`method call, method execution, constructor call, constructor execution, field get,
+field set, pre-initialization, initialization, static initialization, handler,`
+and `advice execution` join points.
 
 The _kinded_ pointcut designators match based on the kind of a join
-point. These are the `call,
-        execution, get, set, preinitialization, initialization,
-        staticinitialization, handler,` and `adviceexecution`
-designators.
+point. These are the `call, execution, get, set, preinitialization, initialization,
+staticinitialization, handler,` and `adviceexecution` designators.
 
 A kinded pointcut is written using patterns, some of which match based
 on _signature_, and some of which match based on _modifiers_. For
@@ -100,7 +97,7 @@ of the target):
 [source, java]
 ....
 T t = new T();
-t.m("hello");  <= call join point occurs when this line is executed
+t.m("hello");  // <= call join point occurs when this line is executed
 ....
 
 Then the signature `R(T) T.m(parameter_types)` is a signature of the
diff --git a/docs/adk15ProgGuideDB/varargs.adoc b/docs/adk15ProgGuideDB/varargs.adoc
index bf644ace3..0f5a7b3df 100644
--- a/docs/adk15ProgGuideDB/varargs.adoc
+++ b/docs/adk15ProgGuideDB/varargs.adoc
@@ -82,13 +82,13 @@ Method and constructor patterns are used in the `call`, `execution`,
 `initialization`, `preinitialization`, and `withincode` pointcut
 designators. Some examples of usage follow:
 
-call(* org.xyz.*.*(int, String...))::
+`call(* org.xyz.*.*(int, String...))`::
   Matches a call join point for a call to a method defined in the
   `org.xyz` package, taking an `int` and a `String vararg`.
-execution(* org.xyz.*.*(Integer...))::
+`execution(* org.xyz.*.*(Integer...))`::
   Matches an execution join point for the execution of a method defined
   in the `org.xyz` package, taking an `Integer vararg`.
-initialization(org.xyz.*.new((Foo || Goo)...))::
+`initialization(org.xyz.*.new((Foo || Goo)...))`::
   Matches the initialization join point for the construction of an
   object in the `org.xyz` package via a constructor taking either a
   variable number of `Foo` parameters or a variable number of `Goo`