groovy git commit: add doco about optional exception declaration within methods

[pa...@apache.org]

Repository: groovy
Updated Branches:
  refs/heads/master f21df9e48 -> d096f801a


add doco about optional exception declaration within methods


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/d096f801
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/d096f801
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/d096f801

Branch: refs/heads/master
Commit: d096f801af9a9e48aa0be0dc764be221e83f2dc3
Parents: f21df9e
Author: paulk <pa...@asert.com.au>
Authored: Mon Jul 18 21:36:13 2016 +1000
Committer: paulk <pa...@asert.com.au>
Committed: Mon Jul 18 21:36:13 2016 +1000

----------------------------------------------------------------------
 src/spec/doc/core-object-orientation.adoc       | 22 +++++++++++-
 .../test/objectorientation/MethodsTest.groovy   | 38 +++++++++++++++++---
 2 files changed, 54 insertions(+), 6 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/groovy/blob/d096f801/src/spec/doc/core-object-orientation.adoc
----------------------------------------------------------------------
diff --git a/src/spec/doc/core-object-orientation.adoc b/src/spec/doc/core-object-orientation.adoc
index d88c38a..c857441 100644
--- a/src/spec/doc/core-object-orientation.adoc
+++ b/src/spec/doc/core-object-orientation.adoc
@@ -389,8 +389,28 @@ include::{projectdir}/src/spec/test/objectorientation/MethodsTest.groovy[tags=va
 
 ==== Exception declaration
 
-(TBD)
+Groovy automatically allows you to treat checked exceptions like unchecked exceptions.
+This means that you don't need to declare any checked exceptions that a method may throw
+as shown in the following example which can throw a `FileNotFoundException` if the file isn't found:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/objectorientation/MethodsTest.groovy[tags=idiomatic_method_declaration,indent=0]
+----
 
+Nor will you be required to surround the call to the `badRead` method in the previous example within a try/catch
+block - though you are free to do so if you wish.
+
+If you wish to declare any exceptions that your code might throw (checked or otherwise) you are free to do so.
+Adding exceptions won't change how the code is used from any other Groovy code but can be seen as documentation
+for the human reader of your code. The exceptions will become part of the method declaration in the bytecode,
+so if your code might be called from Java, it might be useful to include them.
+Using an explicit checked exception declaration is illustrated in the following example:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/objectorientation/MethodsTest.groovy[tags=checked_method_declaration,indent=0]
+----
 
 === Fields and properties
 

http://git-wip-us.apache.org/repos/asf/groovy/blob/d096f801/src/spec/test/objectorientation/MethodsTest.groovy
----------------------------------------------------------------------
diff --git a/src/spec/test/objectorientation/MethodsTest.groovy b/src/spec/test/objectorientation/MethodsTest.groovy
index 0806b9b..1dacf57 100644
--- a/src/spec/test/objectorientation/MethodsTest.groovy
+++ b/src/spec/test/objectorientation/MethodsTest.groovy
@@ -18,7 +18,7 @@
  */
 package objectorientation
 
-class MethodsTests extends GroovyTestCase {
+class MethodsTest extends GroovyTestCase {
 
     void testMethodDefinition() {
         assertScript '''
@@ -59,7 +59,7 @@ class MethodsTests extends GroovyTestCase {
             // end::varargs_example[]
         '''
     }
-    
+
     void testVarargsArrayNotation() {
         assertScript '''
             // tag::varargs_array_notation[]
@@ -70,7 +70,7 @@ class MethodsTests extends GroovyTestCase {
             // end::varargs_array_notation[]
         '''
     }
-    
+
     void testVarargsNullParameter() {
         assertScript '''
             // tag::varargs_null_parameter[]
@@ -79,7 +79,7 @@ class MethodsTests extends GroovyTestCase {
             // end::varargs_null_parameter[]
         '''
     }
-    
+
     void testVarargsArrayParameter() {
         assertScript '''
             // tag::varargs_array_parameter[]
@@ -89,7 +89,7 @@ class MethodsTests extends GroovyTestCase {
             // end::varargs_array_parameter[]
         '''
     }
-    
+
     void testVarargsMethodOverloading() {
         assertScript '''
             // tag::varargs_method_overloading[]
@@ -102,4 +102,32 @@ class MethodsTests extends GroovyTestCase {
         '''
     }
 
+    void testIdiomaticMethodDeclaration() {
+        assertScript '''
+            // tag::idiomatic_method_declaration[]
+            def badRead() {
+                new File('doesNotExist.txt').text
+            }
+
+            shouldFail(FileNotFoundException) {
+                badRead()
+            }
+            // end::idiomatic_method_declaration[]
+        '''
+    }
+
+    void testMethodDeclarationWithCheckedException() {
+        assertScript '''
+            // tag::checked_method_declaration[]
+            def badRead() throws FileNotFoundException {
+                new File('doesNotExist.txt').text
+            }
+
+            shouldFail(FileNotFoundException) {
+                badRead()
+            }
+            // end::checked_method_declaration[]
+        '''
+    }
+
 }