[groovy] 01/03: documentation: start to flesh out builder TBDs

[pa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch GROOVY_4_0_X
in repository https://gitbox.apache.org/repos/asf/groovy.git

commit 5f1e3a70296e4c75e0931805c8d074a079e035d0
Author: Paul King <pa...@asert.com.au>
AuthorDate: Fri Jan 7 22:37:31 2022 +1000

    documentation: start to flesh out builder TBDs
---
 src/spec/doc/core-domain-specific-languages.adoc | 44 ++++++++++++++++--------
 src/spec/doc/core-semantics.adoc                 |  2 +-
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/src/spec/doc/core-domain-specific-languages.adoc b/src/spec/doc/core-domain-specific-languages.adoc
index aba0332..d251ab9 100644
--- a/src/spec/doc/core-domain-specific-languages.adoc
+++ b/src/spec/doc/core-domain-specific-languages.adoc
@@ -1038,23 +1038,16 @@ link:type-checking-extensions.html[type checking extensions].
 
 == Builders
 
-(TBD)
-
-=== Creating a builder
-
-(TBD)
-
-==== BuilderSupport
-
-(TBD)
-
-==== FactoryBuilderSupport
-
-(TBD)
+Many tasks require building things and the builder pattern is one technique
+used by developers to make building things easier, especially building
+of structures which are hierarchical in nature.
+This pattern is so ubiquitous that Groovy has special built-in support.
+Firstly, there are many built-in builders. Secondly, there are
+classes which make it easier to write your own builders.
 
 === Existing builders
 
-(TBD)
+Groovy comes with many built-in builders. Let's look at some of them.
 
 ==== MarkupBuilder
 
@@ -1801,3 +1794,26 @@ This produces the same directory structure as above, as shown by these `assert`s
 ----
 include::../test/builder/FileTreeBuilderTest.groovy[tags=shorthand_syntax_assert,indent=0]
 ----
+
+=== Creating a builder
+
+While Groovy has many builders built-in, this pattern is so common,
+you will no doubt eventually come across a building requirement that
+hasn't been catered for by those built-in builders.
+The good news is that you can build your own.
+You can do everything from scratch by relying on Groovy's
+metaprogramming capabilities. Alternatively, the `BuilderSupport`
+and `FactoryBuilderSupport` classes are specially designed to make building
+builders easy.
+
+==== BuilderSupport
+
+One approach to building a builder is to subclass `BuilderSupport`.
+
+(TBD)
+
+==== FactoryBuilderSupport
+
+A second approach to building a builder is to subclass `FactoryBuilderSupport`.
+
+(TBD)
diff --git a/src/spec/doc/core-semantics.adoc b/src/spec/doc/core-semantics.adoc
index fdbdb5e..2098da4 100644
--- a/src/spec/doc/core-semantics.adoc
+++ b/src/spec/doc/core-semantics.adoc
@@ -609,7 +609,7 @@ include::../test/semantics/GPathTest.groovy[tags=gpath_on_xml_1,indent=0]
 <4> Text value of `key` element of first `keyVal` element of second `sublevel` element under `root/level` is 'anotherKey'
 
 Further details about GPath expressions for XML are in the
-link:../../../subprojects/groovy-xml/src/spec/doc/xml-userguide.adoc[XML User Guide].
+<<{xml-userguide}#processing-xml,XML User Guide>>.
 
 == Promotion and coercion