Documentation. Adding JavaDoc comments. Adjustments to method names.

4 files changed, 76 insertions, 36 deletions

diff --git a/src/com/gitblit/build/Build.java b/src/com/gitblit/build/Build.java
index 641b7aa7..998e7ba6 100644
--- a/src/com/gitblit/build/Build.java
+++ b/src/com/gitblit/build/Build.java
@@ -35,6 +35,18 @@ import java.util.Properties;
 import com.gitblit.Constants;

 import com.gitblit.utils.StringUtils;

 

+/**

+ * The Build class downloads runtime and compile-time jar files from the Apache

+ * or Eclipse Maven repositories.

+ * 

+ * It also generates the Keys class from the gitblit.properties file.

+ * 

+ * Its important that this class have minimal compile dependencies since its

+ * called very early in the build script.

+ * 

+ * @author James Moger

+ * 

+ */

 public class Build {

 

 	public static enum BuildType {

@@ -95,6 +107,10 @@ public class Build {
 		downloadFromApache(MavenObject.COMMONSNET, BuildType.RUNTIME);

 	}

 

+	/**

+	 * Builds the Keys class based on the gitblit.properties file and inserts

+	 * the class source into the project source folder.

+	 */

 	public static void buildSettingKeys() {

 		// Load all keys

 		Properties properties = new Properties();

diff --git a/src/com/gitblit/build/BuildSite.java b/src/com/gitblit/build/BuildSite.java
index 5a9825aa..81cc8f29 100644
--- a/src/com/gitblit/build/BuildSite.java
+++ b/src/com/gitblit/build/BuildSite.java
@@ -15,7 +15,6 @@
  */

 package com.gitblit.build;

 

-import java.io.BufferedReader;

 import java.io.File;

 import java.io.FileInputStream;

 import java.io.FileOutputStream;

@@ -37,9 +36,21 @@ import com.beust.jcommander.Parameter;
 import com.beust.jcommander.ParameterException;

 import com.beust.jcommander.Parameters;

 import com.gitblit.Constants;

+import com.gitblit.utils.FileUtils;

 import com.gitblit.utils.MarkdownUtils;

 import com.gitblit.utils.StringUtils;

 

+/**

+ * Builds the web site or deployment documentation from Markdown source files.

+ * 

+ * All Markdown source files must have the .mkd extension.

+ * 

+ * Natural string sort order of the Markdown source filenames is the order of

+ * page links. "##_" prefixes are used to control the sort order.

+ * 

+ * @author James Moger

+ * 

+ */

 public class BuildSite {

 

 	public static void main(String... args) {

@@ -87,8 +98,8 @@ public class BuildSite {
 		sb.setLength(sb.length() - 3);

 		sb.trimToSize();

 

-		String htmlHeader = readContent(new File(params.pageHeader), "\n");

-		String htmlFooter = readContent(new File(params.pageFooter), "\n");

+		String htmlHeader = FileUtils.readContent(new File(params.pageHeader), "\n");

+		String htmlFooter = FileUtils.readContent(new File(params.pageFooter), "\n");

 		final String links = sb.toString();

 		final String header = MessageFormat.format(htmlHeader, Constants.FULL_NAME, links);

 		final String date = new SimpleDateFormat("yyyy-MM-dd").format(new Date());

@@ -109,7 +120,7 @@ public class BuildSite {
 					}

 					for (String alias : params.loads) {

 						String[] kv = alias.split("=");

-						String loadedContent = readContent(new File(kv[1]), "\n");

+						String loadedContent = FileUtils.readContent(new File(kv[1]), "\n");

 						loadedContent = StringUtils.escapeForHtml(loadedContent, false);

 						loadedContent = StringUtils.breakLinesForHtml(loadedContent);

 						content = content.replace(kv[0], loadedContent);

@@ -129,32 +140,15 @@ public class BuildSite {
 		}

 	}

 

-	private static String readContent(File file, String lineEnding) {

-		StringBuilder sb = new StringBuilder();

-		try {

-			InputStreamReader is = new InputStreamReader(new FileInputStream(file),

-					Charset.forName("UTF-8"));

-			BufferedReader reader = new BufferedReader(is);

-			String line = null;

-			while ((line = reader.readLine()) != null) {

-				sb.append(line);

-				if (lineEnding != null) {

-					sb.append(lineEnding);

-				}

-			}

-			reader.close();

-		} catch (Throwable t) {

-			System.err.println("Failed to read content of " + file.getAbsolutePath());

-			t.printStackTrace();

-		}

-		return sb.toString();

-	}

-

 	private static String getDocumentName(File file) {

 		String displayName = file.getName().substring(0, file.getName().lastIndexOf('.'))

 				.toLowerCase();

-		// trim leading ##_ which is to control display order

-		return displayName.substring(3);

+		int underscore = displayName.indexOf('_') + 1;

+		if (underscore > -1) {

+			// trim leading ##_ which is to control display order

+			return displayName.substring(underscore);

+		}

+		return displayName;

 	}

 

 	private static void usage(JCommander jc, ParameterException t) {

diff --git a/src/com/gitblit/build/BuildThumbnails.java b/src/com/gitblit/build/BuildThumbnails.java
index f1bdbdef..0676ecaf 100644
--- a/src/com/gitblit/build/BuildThumbnails.java
+++ b/src/com/gitblit/build/BuildThumbnails.java
@@ -22,6 +22,7 @@ import java.io.File;
 import java.io.FileOutputStream;

 import java.io.FilenameFilter;

 import java.io.IOException;

+import java.text.MessageFormat;

 import java.util.Iterator;

 

 import javax.imageio.ImageIO;

@@ -33,6 +34,12 @@ import com.beust.jcommander.Parameter;
 import com.beust.jcommander.ParameterException;

 import com.beust.jcommander.Parameters;

 

+/**

+ * Generates PNG thumbnails of the PNG images from the specified source folder.

+ * 

+ * @author James Moger

+ * 

+ */

 public class BuildThumbnails {

 

 	public static void main(String[] args) {

@@ -47,6 +54,15 @@ public class BuildThumbnails {
 		createImageThumbnail(params.sourceFolder, params.destinationFolder, params.maximumDimension);

 	}

 

+	/**

+	 * Generates thumbnails from all PNG images in the source folder and saves

+	 * them to the destination folder.

+	 * 

+	 * @param sourceFolder

+	 * @param destinationFolder

+	 * @param maxDimension

+	 *            the maximum height or width of the image.

+	 */

 	public static void createImageThumbnail(String sourceFolder, String destinationFolder,

 			int maxDimension) {

 		if (maxDimension <= 0)

@@ -71,18 +87,18 @@ public class BuildThumbnails {
 					// Scale to Width

 					w = maxDimension;

 					float f = maxDimension;

-					h = (int) ((f / sz.width) * sz.height); // normalize height

+					// normalize height

+					h = (int) ((f / sz.width) * sz.height);

 				} else if (sz.height > maxDimension) {

 					// Scale to Height

 					h = maxDimension;

 					float f = maxDimension;

-					w = (int) ((f / sz.height) * sz.width); // normalize width

-				} else {

-					// No thumbnail

-					return;

+					// normalize width

+					w = (int) ((f / sz.height) * sz.width);

 				}

-				System.out.println("Generating thumbnail for " + sourceFile.getName() + " as (" + w

-						+ "," + h + ")");

+				System.out.println(MessageFormat.format(

+						"Generating thumbnail for {0} as ({1,number,#}, {2,number,#})",

+						sourceFile.getName(), w, h));

 				BufferedImage image = ImageIO.read(sourceFile);

 				Image scaledImage = image.getScaledInstance(w, h, BufferedImage.SCALE_SMOOTH);

 				BufferedImage destImage = new BufferedImage(w, h, BufferedImage.TYPE_INT_RGB);

@@ -98,6 +114,13 @@ public class BuildThumbnails {
 		}

 	}

 

+	/**

+	 * Return the dimensions of the specified image file.

+	 * 

+	 * @param file

+	 * @return dimensions of the image

+	 * @throws IOException

+	 */

 	public static Dimension getImageDimensions(File file) throws IOException {

 		ImageInputStream in = ImageIO.createImageInputStream(file);

 		try {

diff --git a/src/com/gitblit/build/BuildWebXml.java b/src/com/gitblit/build/BuildWebXml.java
index c37f0147..e53a4aff 100644
--- a/src/com/gitblit/build/BuildWebXml.java
+++ b/src/com/gitblit/build/BuildWebXml.java
@@ -29,9 +29,15 @@ import com.beust.jcommander.Parameter;
 import com.beust.jcommander.ParameterException;

 import com.beust.jcommander.Parameters;

 import com.gitblit.Keys;

-import com.gitblit.Keys.server;

 import com.gitblit.utils.StringUtils;

 

+/**

+ * Builds the Gitblit WAR web.xml file by merging the Gitblit GO web.xml file

+ * with the gitblit.properties comments, settings, and values.

+ * 

+ * @author James Moger

+ * 

+ */

 public class BuildWebXml {

 	private static final String PARAMS = "<!-- PARAMS -->";

 

@@ -88,7 +94,8 @@ public class BuildWebXml {
 			for (String comment : setting.comments) {

 				parameters.append(MessageFormat.format(COMMENT_PATTERN, comment));

 			}

-			parameters.append(MessageFormat.format(PARAM_PATTERN, setting.name, StringUtils.escapeForHtml(setting.value, false)));

+			parameters.append(MessageFormat.format(PARAM_PATTERN, setting.name,

+					StringUtils.escapeForHtml(setting.value, false)));

 		}

 

 		// Read the prototype web.xml file