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

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


The following commit(s) were added to refs/heads/asf-site by this push:
     new c87cb0d  Improve Groovydoc section in release notes
c87cb0d is described below

commit c87cb0d032da4c1a5db83285316c6415c97bd02e
Author: Paddy <p.with...@gmail.com>
AuthorDate: Thu Dec 13 16:59:09 2018 +1000

    Improve Groovydoc section in release notes
---
 site/src/site/releasenotes/groovy-3.0.adoc | 80 +++++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 19 deletions(-)

diff --git a/site/src/site/releasenotes/groovy-3.0.adoc 
b/site/src/site/releasenotes/groovy-3.0.adoc
index 372c833..c0a663d 100644
--- a/site/src/site/releasenotes/groovy-3.0.adoc
+++ b/site/src/site/releasenotes/groovy-3.0.adoc
@@ -450,32 +450,74 @@ a| NOTE: _Experimental Status:_ While this feature will 
remain, we regard its cu
 [[Groovy3.0releasenotes-Miscimprovements]]
 == Miscellaneous improvements
 
-=== Embedded GroovyDoc
+=== Embedded Groovydoc
 
-You can now embed Groovydoc in various ways.
+You can now embed Groovydoc comments in various ways:
 
-It can be attached to the AST as node metadata and available during 
compilation for use by for instance
-AST transformations or other tools. This is enabled using the 
`groovy.attach.groovydoc` system property.
+* They can be made available within the AST for use by AST transformations and 
other tools.
+Our revamped groovydoc tool (still under development) is based on this 
capability.
+Behind the scenes the groovydoc content is stored as node metadata but a 
simple API
+hides this implementation detail.
+This feature is enabled using the `groovy.attach.groovydoc` system property or
+corresponding flag in `CompilerConfiguration`.
 
-It can also be embedded into the class file via an annotation and available at 
runtime for access
-via reflection or via other tools. This is enabled using the 
'groovy.attach.runtime.groovydoc' system property
-to globally enable the attachment of all Groovydoc or by using a special 
`@Groovydoc` tag/annotation at
-the start of any Groovydoc comment. You normally don't deal with the 
annotation directly - the compiler handles
-proper placement of the annotation and an extension method allows easy access 
to the Groovydoc comment value.
-Here is a typical example:
+* Groovydoc comments starting with a special `/**@` opening comment delimiter 
can also be embedded into the class file
+(behind the scenes it's stored in a @Groovydoc annotation) and is available at 
runtime for access
+via reflection or via other tools. This is enabled using the 
`groovy.attach.runtime.groovydoc` system
+property or corresponding flag in `CompilerConfiguration`. This provides a 
capability in Groovy inspired
+by languages like Ruby which can embed documentation into the standard binary 
jar and is thus always available
+rather than relying on a separate javadoc jar.
+
+Here is an example illustrating access to groovydoc comments within the AST:
 
 [source,groovy]
 --------------------------------------
-/** fee fi */
-class Foo {
-    /** @Groovydoc fo fum */
-    def bar() { }
+import org.codehaus.groovy.control.*
+
+def cc = new CompilerConfiguration(optimizationOptions:
+    [(CompilerConfiguration.GROOVYDOC): true])
+
+def ast = new CompilationUnit(cc).tap {
+    addSource 'myScript.groovy', '''
+        /** class doco */
+        class MyClass {
+            /** method doco */
+            def myMethod() {}
+        }
+    '''
+    compile Phases.SEMANTIC_ANALYSIS
+}.ast
+
+def classDoc = ast.classes[0].groovydoc
+assert classDoc.content.contains('class doco')
+def methodDoc = ast.classes[0].methods[0].groovydoc
+assert methodDoc.content.contains('method doco')
+--------------------------------------
+
+Here is an example using illustrating runtime groovydoc (with and without the 
flag set):
+
+[source,groovy]
+--------------------------------------
+import org.codehaus.groovy.control.*
+
+def extract(shell) {
+    shell.evaluate( '''
+        /**@
+         * Some class groovydoc for Foo
+         */
+        class Foo {}
+        Foo.class
+        '''
+    ).groovydoc.content.replaceAll('[^\\w\\s]', '').trim()
 }
-// next line assumes groovy.attach.runtime.groovydoc system property is true
-assert Foo.class.groovydoc.content.contains('fee fi')
-def bar = Foo.methods.find{ it.name == 'bar' }
-// next line always true due to explicit @Groovydoc
-assert bar.groovydoc.content.contains('@Groovydoc fo fum')
+
+// first without the flag set
+assert extract(new GroovyShell()) == ''
+
+// now with embedding turned on
+def cc = new CompilerConfiguration(optimizationOptions:
+    [(CompilerConfiguration.RUNTIME_GROOVYDOC): true])
+assert extract(new GroovyShell(cc)) == 'Some class groovydoc for Foo'
 --------------------------------------
 
 === JSR308 improvements (work in progress)

Reply via email to