From 2c6130a514b5a4699aa1eefe53773b868fab742f Mon Sep 17 00:00:00 2001
From: Jan Mewes <jan.mewes@ks-plus.org>
Date: Fri, 30 Mar 2018 12:50:03 +0200
Subject: [PATCH] Document role based authorization for packages

---
 .gitignore                                    |  2 ++
 .../annotations/AuthorizeInstantiation.java   | 20 ++++++++++++++-----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/.gitignore b/.gitignore
index a30f497e615..ea43d21e617 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,8 @@ velocity.log
 **velocity.log*
 *.idea/
 *.iml
+*.ipr
+*.iws
 *~
 release.properties
 **/node/
diff --git a/wicket-auth-roles/src/main/java/org/apache/wicket/authroles/authorization/strategies/role/annotations/AuthorizeInstantiation.java b/wicket-auth-roles/src/main/java/org/apache/wicket/authroles/authorization/strategies/role/annotations/AuthorizeInstantiation.java
index 3bf46001b00..f2cf20decbf 100644
--- a/wicket-auth-roles/src/main/java/org/apache/wicket/authroles/authorization/strategies/role/annotations/AuthorizeInstantiation.java
+++ b/wicket-auth-roles/src/main/java/org/apache/wicket/authroles/authorization/strategies/role/annotations/AuthorizeInstantiation.java
@@ -25,20 +25,30 @@
 
 /**
  * Annotation for configuring what roles are allowed for instantiation the annotated component or
- * package. This annotation can be used for classes and packages, and can be used like this:
- * 
+ * package. This annotation can be used for classes and packages. For classes it can be used like this:
+ *
  * <pre>
  *  // only users with role ADMIN are allowed to create instances of this page, whether it is
  *  // either bookmarkable or not
  *  &#064;AuthorizeInstantiation(&quot;ADMIN&quot;)
  *  public class AdminAnnotationsBookmarkablePage extends WebPage
  * </pre>
- * 
+ *
+ * For packages the annotation needs to be specified in the <code>package-info.java</code> file:
+ *
+ * <pre>
+ *  // only users with role ADMIN are allowed to create instances of pages in this package
+ *  &#064;AuthorizeInstantiation(&quot;ADMIN&quot;)
+ *  package package_name;
+ *
+ *  import org.apache.wicket.authroles.authorization.strategies.role.annotations.AuthorizeInstantiation;
+ * </pre>
+ *
  * @see org.apache.wicket.authorization.IAuthorizationStrategy
  * @see AnnotationsRoleAuthorizationStrategy
  * @see AuthorizeActions
  * @see AuthorizeAction
- * 
+ *
  * @author Eelco hillenius
  */
 @Retention(RetentionPolicy.RUNTIME)
@@ -49,7 +59,7 @@
 
 	/**
 	 * Gets the roles that are allowed to take the action.
-	 * 
+	 *
 	 * @return the roles that are allowed. Returns a zero length array by default
 	 */
 	String[] value() default { };