From 3f67eba2e4663841dd0024908f8ffb2613078140 Mon Sep 17 00:00:00 2001
From: Georg Lukas <georg@op-co.de>
Date: Mon, 29 Sep 2014 13:42:13 +0200
Subject: [PATCH] example: add javadoc to JULHandler

---
 .../src/de/duenndns/mtmexample/JULHandler.java   | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/example/src/de/duenndns/mtmexample/JULHandler.java b/example/src/de/duenndns/mtmexample/JULHandler.java
index 88b440b..40f71f5 100644
--- a/example/src/de/duenndns/mtmexample/JULHandler.java
+++ b/example/src/de/duenndns/mtmexample/JULHandler.java
@@ -17,20 +17,21 @@
 /**
  * A <code>java.util.logging</code> (JUL) Handler for Android.
  * <p>
- * In order to initialize JULHandler, call {@link #initialize()}.
+ * If you want fine-grained control over MTM's logging, you can copy this
+ * class to your code base and call the static {@link #initialize()} method.
  * </p>
  * <p>
  * This JUL Handler passes log messages sent to JUL to the Android log, while
- * keeping the format and stack traces from eventually existing Exceptions. It
+ * keeping the format and stack traces of optionally supplied Exceptions. It
  * further allows to install a {@link DebugLogSettings} class via
- * {@link #setDebugLogSettings(DebugLogSettings)} that determines whenever JUL log messages of
+ * {@link #setDebugLogSettings(DebugLogSettings)} that determines whether JUL log messages of
  * level {@link java.util.logging.Level#FINE} or lower are logged. This gives
  * the application developer more control over the logged messages, while
  * allowing a library developer to place debug log messages without risking to
  * spam the Android log.
  * </p>
  * <p>
- * If there are no {@code DebugLogSettings} configured, then all messages send
+ * If there are no {@code DebugLogSettings} configured, then all messages sent
  * to JUL will be logged.
  * </p>
  * 
@@ -40,6 +41,8 @@
 @SuppressWarnings("deprecation")
 public class JULHandler extends Handler {
 
+	/** Implement this interface to toggle debug logging.
+	 */
 	public interface DebugLogSettings {
 		public boolean isDebugLogEnabled();
 	}
@@ -64,6 +67,7 @@ public interface DebugLogSettings {
 );
 // @formatter:on
 
+	// Constants for Android vs. JUL debug level comparisons
 	private static final int FINE_INT = Level.FINE.intValue();
 	private static final int INFO_INT = Level.INFO.intValue();
 	private static final int WARN_INT = Level.WARNING.intValue();
@@ -71,6 +75,7 @@ public interface DebugLogSettings {
 
 	private static final Logger LOGGER = Logger.getLogger(CLASS_NAME);
 
+	/** A formatter that creates output similar to Android's Log.x. */
 	private static final Formatter FORMATTER = new Formatter() {
 		@Override
 		public String format(LogRecord logRecord) {
@@ -131,6 +136,7 @@ public boolean isLoggable(LogRecord record) {
 		return true;
 	}
 
+	/** JUL method that forwards log records to Android's LogCat. */
 	@Override
 	public void publish(LogRecord record) {
 		if (!isLoggable(record)) return;
@@ -142,6 +148,7 @@ public void publish(LogRecord record) {
 		Log.println(priority, tag, msg);
 	}
 
+	/** Helper to convert JUL verbosity levels to Android's Log. */
 	private static int getAndroidPriority(Level level) {
 		int value = level.intValue();
 		if (value >= SEVE_INT) {
@@ -155,6 +162,7 @@ private static int getAndroidPriority(Level level) {
 		}
 	}
 
+	/** Helper to extract short class names. */
 	private static String substringAfterLastDot(String s) {
 		return s.substring(s.lastIndexOf('.') + 1).trim();
 	}