Add some Javadoc comments

server-core/src/main/java/io/onedev/server/ci/DefaultCISpecProvider.java

@@ -7,6 +7,19 @@ import org.eclipse.jgit.lib.ObjectId;
 import io.onedev.commons.launcher.loader.ExtensionPoint;
 import io.onedev.server.model.Project;
 
+/**
+ * This extension point extends OneDev's ability to provide default CI spec for different 
+ * kinds of projects 
+ * <p>
+ * OneDev has built-in CI support to build projects. The build instructions are defined in <i>onedev-ci.xml</i> 
+ * in root of the project (do not worry about writing this xml, OneDev has visual editor to help you doing
+ * that). For some typical projects, it is possible that some default build instructions can be deducted 
+ * automatically without existence of <i>onedev-ci.xml</i>. Hence we introduced this extension point to make 
+ * OneDev CI more easier to get started.
+ * 
+ * @author robin
+ *
+ */
 @ExtensionPoint
 public interface DefaultCISpecProvider {
 	
@@ -22,6 +35,14 @@ public interface DefaultCISpecProvider {
 	@Nullable
 	CISpec getDefaultCISpec(Project project, ObjectId commitId);
 	
+	/**
+	 * Get priority of this provider. If multiple providers can provide default CI specs for 
+	 * specified project and commit, the provider with higher priority will win
+	 * 
+	 * @return
+	 * 			a number indicating priority of the provider. The lower the value is, the 
+	 *			higher the priority is
+	 */
 	int getPriority();
 	
 }

server-core/src/main/java/io/onedev/server/ci/job/Job.java

@@ -97,7 +97,7 @@ public class Job implements Serializable, Validatable {
 	}
 
 	@Editable(order=120, description="Specify commands to execute in above environment, with one command per line. "
-			+ "For Windows based environments, commands will be interpretated by PowerShell, and for Unix/Linux "
+			+ "For Windows based environments, commands will be interpretated by cmd.exe, and for Unix/Linux "
 			+ "based environments, commands will be interpretated by shell")
 	@Script(Script.SHELL)
 	@NotEmpty

server-core/src/main/java/io/onedev/server/ci/job/log/DefaultLogManager.java

@@ -103,10 +103,11 @@ public class DefaultLogManager implements LogManager {
 
 			private void log(LogLevel logLevel, String message) {
 				for (LogNormalizer logNormalizer: logNormalizers) {
-					LogNormalizer.Result result = logNormalizer.normalize(message);
+					LogNormalizer.Normalized normalized = logNormalizer.normalize(message);
-					if (result != null) {
+					if (normalized != null) {
-						logLevel = result.getLevel();
+						if (normalized.getLevel() != null)
-						message = result.getMessage();
+							logLevel = normalized.getLevel();
+						message = normalized.getMessage();
 						break;
 					}
 				}

server-core/src/main/java/io/onedev/server/ci/job/log/LogNormalizer.java

@@ -4,27 +4,56 @@ import javax.annotation.Nullable;
 
 import io.onedev.commons.launcher.loader.ExtensionPoint;
 
+/**
+ * Sometimes job log message needs to be normalized for better display. For instance Maven command prints something 
+ * like below:
+ * 
+ * <pre>[INFO] Scanning for projects...</pre>
+ * 
+ * In such case, we should extract the log level information to override OneDev's default log level, and the 
+ * original message should also be modified to remove the log level information
+ * 
+ * @author robin
+ *
+ */
 @ExtensionPoint
 public interface LogNormalizer {
 	
+	/**
+	 * Normalize provided job log message  
+	 * @param message
+	 * 			message to be normalized
+	 * @return
+	 * 			normalized result, or <tt>null</tt> if this normalizer does not handle this message
+	 */
 	@Nullable
-	Result normalize(String message);
+	Normalized normalize(String message);
 	
-	public static class Result {
+	public static class Normalized {
 
 		private final LogLevel level;
 		
 		private final String message;
 		
-		public Result(LogLevel level, String message) {
+		public Normalized(@Nullable LogLevel level, String message) {
 			this.level = level;
 			this.message = message;
 		}
 
+		/**
+		 * @return 
+		 * 			Log level of this message, or <tt>null</tt> if log level information 
+		 * 			is not available in this message
+		 */
+		@Nullable
 		public LogLevel getLevel() {
 			return level;
 		}
 
+		/**
+		 * @return 
+		 * 			normalized message  
+		 */
 		public String getMessage() {
 			return message;
 		}

server-plugin/server-plugin-maven/src/main/java/io/onedev/server/plugin/maven/DefaultMavenCISpecProvider.java

@@ -63,6 +63,7 @@ public class DefaultMavenCISpecProvider implements DefaultCISpecProvider {
 			Job job = new Job();
 
 			job.setName("ci");
+			
 			switch (javaVersion) {
 			case "13":
 				job.setEnvironment("maven:3.6.1-jdk-13");
@@ -76,15 +77,25 @@ public class DefaultMavenCISpecProvider implements DefaultCISpecProvider {
 			default:
 				job.setEnvironment("maven:3.6.1-jdk-8");
 			}
+
+			/*
+			 * Before running maven test, we extract version of the project and use LogInstruction to tell 
+			 * OneDev using extracted version for current build
+			 */
 			job.setCommands(""
 					+ "buildVersion=$(mvn org.apache.maven.plugins:maven-help-plugin:3.1.0:evaluate -Dexpression=project.version -q -DforceStdout)\n"
 					+ "echo \"##onedev[SetBuildVersion '$buildVersion']\"\n"
 					+ "echo\n" 
 					+ "mvn clean test");
 
+			// Trigger the job automatically when there is a push to the branch			
 			BranchUpdateTrigger trigger = new BranchUpdateTrigger();
 			job.getTriggers().add(trigger);
 			
+			/*
+			 * Cache Maven local repository in order not to download Maven dependencies all over again for 
+			 * subsequent builds
+			 */
 			JobCache cache = new JobCache();
 			cache.setKey("maven-local-repository");
 			cache.setPath("/root/.m2");

server-plugin/server-plugin-maven/src/main/java/io/onedev/server/plugin/maven/MavenLogNormalizer.java

@@ -9,17 +9,17 @@ import io.onedev.server.ci.job.log.LogNormalizer;
 public class MavenLogNormalizer implements LogNormalizer {
 
 	@Override
-	public Result normalize(String message) {
+	public Normalized normalize(String message) {
 		if (message.startsWith("[INFO] ")) {
-			return new Result(LogLevel.INFO, message.substring("[INFO] ".length()));
+			return new Normalized(LogLevel.INFO, message.substring("[INFO] ".length()));
 		} else if (message.startsWith("[ERROR] ")) {
-			return new Result(LogLevel.ERROR, message.substring("[ERROR] ".length()));
+			return new Normalized(LogLevel.ERROR, message.substring("[ERROR] ".length()));
 		} else if (message.startsWith("[WARNING] ")) {
-			return new Result(LogLevel.WARN, message.substring("[WARNING] ".length()));
+			return new Normalized(LogLevel.WARN, message.substring("[WARNING] ".length()));
 		} else if (message.startsWith("[DEBUG] ")) {
-			return new Result(LogLevel.DEBUG, message.substring("[DEBUG] ".length()));
+			return new Normalized(LogLevel.DEBUG, message.substring("[DEBUG] ".length()));
 		} else if (message.startsWith("[TRACE] ")) {
-			return new Result(LogLevel.TRACE, message.substring("[TRACE] ".length()));
+			return new Normalized(LogLevel.TRACE, message.substring("[TRACE] ".length()));
 		} else {
 			return null;
 		}