From 0f68090e02ab53fc067ad9b00a49530ed84b93f5 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Felix=20D=C3=B6rre?= <felix@dogcraft.de>
Date: Thu, 26 Jun 2014 16:51:27 +0200
Subject: [PATCH] Briefly document "Page"

---
 src/org/cacert/gigi/pages/Page.java | 60 +++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 3 deletions(-)

diff --git a/src/org/cacert/gigi/pages/Page.java b/src/org/cacert/gigi/pages/Page.java
index 386a6d75..04f1dc67 100644
--- a/src/org/cacert/gigi/pages/Page.java
+++ b/src/org/cacert/gigi/pages/Page.java
@@ -12,6 +12,10 @@ import javax.servlet.http.HttpServletResponse;
 import org.cacert.gigi.Language;
 import org.cacert.gigi.output.Template;
 
+/**
+ * This class encapsulates a sub page of Gigi. A template residing nearby this
+ * class with name &lt;className&gt;.templ will be loaded automatically.
+ */
 public abstract class Page {
 	private String title;
 	private Template defaultTemplate;
@@ -29,22 +33,75 @@ public abstract class Page {
 			e.printStackTrace();
 		}
 	}
+
+	/**
+	 * Retrives the default template (&lt;className&gt;.templ) which has already
+	 * been loaded.
+	 * 
+	 * @return the default template.
+	 */
 	public Template getDefaultTemplate() {
 		return defaultTemplate;
 	}
 
+	/**
+	 * This method can be overridden to execute code and do stuff before the
+	 * default template is applied.
+	 * 
+	 * @param req
+	 *            the request to handle.
+	 * @param resp
+	 *            the response to write to
+	 * @return true, iff the request is consumed and the default template should
+	 *         not be applied.
+	 * @throws IOException
+	 *             if output goes wrong.
+	 */
 	public boolean beforeTemplate(HttpServletRequest req,
 			HttpServletResponse resp) throws IOException {
 		return false;
 	}
+
+	/**
+	 * This method is called to generate the content inside the default
+	 * template.
+	 * 
+	 * @param req
+	 *            the request to handle.
+	 * @param resp
+	 *            the response to write to
+	 * @throws IOException
+	 *             if output goes wrong.
+	 */
 	public abstract void doGet(HttpServletRequest req, HttpServletResponse resp)
 			throws IOException;
 
+	/**
+	 * Same as {@link #doGet(HttpServletRequest, HttpServletResponse)} but for
+	 * POST requests. By default they are redirected to
+	 * {@link #doGet(HttpServletRequest, HttpServletResponse)};
+	 * 
+	 * @param req
+	 *            the request to handle.
+	 * @param resp
+	 *            the response to write to
+	 * @throws IOException
+	 *             if output goes wrong.
+	 */
 	public void doPost(HttpServletRequest req, HttpServletResponse resp)
 			throws IOException {
 		doGet(req, resp);
 	}
 
+	/**
+	 * Returns true, iff this page requires login. Default is <code>true</code>
+	 * 
+	 * @return iff the page needs login.
+	 */
+	public boolean needsLogin() {
+		return true;
+	}
+
 	public String getTitle() {
 		return title;
 	}
@@ -60,8 +117,5 @@ public abstract class Page {
 		Language l = getLanguage(req);
 		return l.getTranslation(string);
 	}
-	public boolean needsLogin() {
-		return true;
-	}
 
 }
-- 
2.39.2