Writing Your Own Module

So you want to write an analysis module, eh? OK, we'll do so for a simple module that reports on the basics of what Javadoc finds.

Step 1: Creating an analysis class
The start of each analysis class should contain both the GNU license v3, and the class should be packaged in the comtor.analyzers package in the source tree. /** * Comment Mentor: A Comment Quality Assessment Tool * Copyright (C) 2011 The College of New Jersey * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by *  the Free Software Foundation, either version 3 of the License, or *  (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ package comtor.analyzers;

Next, your new class will need to implement the ComtorDoclet interface. While it likely is a bad name to call what you are building a Doclet, we'll just continue to use this approach until we rewrite the application using ANTLR.

public interface ComtorDoclet { /** 	 * The analyze method in each analysis module performs the analysis and * operates on the parsed source code (parsed by Javadoc program) as a * com.sun.javadoc.RootDoc object. The method returns a property list with * the grading results and the report. */ 	public Properties analyze(RootDoc root); /** 	 * Sets the grading breakdown for the doclet. * 	 * @param section The name of the section for which the max grade is set * @param maxGrade The maximum grade for the section */ 	public void setGradingBreakdown(String section, float maxGrade); /** 	 * Returns the grade for the doclet. * 	 * @return returns a float value of the grade for the doclet (post-processing) */ 	public float getGrade; /** 	 * Sets a parameter used for doclet grading. * 	 * @param param The name of the grading parameter * @param value The value of the grading parameter */ 	public void setGradingParameter(String param, String value); /** 	 * Sets the configuration properties loaded from the config file * 	 * @param props A Properties list object containing any module configuration * properties. */ 	public void setConfigProperties(Properties props); }

For the time being, we'll skip development of the setGradingBreakdown, getGrade, setGradingParameter, and setConfigProperties methods, as they are used with the web-based version. Our first module development attempt will solely develop just the analyze method to provide some basic information about what Javadoc has access to in the submitted code. Of course, we're going to need to implement those 'skipped' methods, but it will just be a basic implementation for now.

So our first attempt at a simple module would look something like the following: /** * Comment Mentor: A Comment Quality Assessment Tool * Copyright (C) 2011 The College of New Jersey * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by *  the Free Software Foundation, either version 3 of the License, or *  (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ package comtor.analyzers;

import comtor.*; import com.sun.javadoc.*; import java.util.*;

/** * The BasicInfo analyzer provides basic information about what Javadoc finds. This module is used * as a pedagogical tool for those learning to develop for COMTOR as well as a simple debugging * aid for those in need of knowing what is going on inside of COMTOR (consider this a dump * of the most relevant parts of the RootDoc). * * @author Peter DePasquale */ public class BasicInfo implements ComtorDoclet { /**	 * The analyze method in each analysis module performs the analysis and * operates on the parsed source code (parsed by Javadoc program) as a * com.sun.javadoc.RootDoc object. The method returns a property list with * the grading results and the report. */	public Properties analyze(RootDoc root) { return null; }

/*	 * Sets the grading breakdown for the doclet. *	 * @param section Name of the section to set the max grade for * @param maxGrade Maximum grade for the section */	public void setGradingBreakdown(String section, float maxGrade) {		// Not needed for this analyzer }	/**	 * Sets a parameter used for doclet grading. *	 * @param param Name of the grading parameter * @param value Value of the parameter */	public void setGradingParameter(String param, String value) { // Not needed for this analyzer }

/**	 * Returns the grade for the doclet. *	 * @return the overall grade for the doclet, as a float */	public float getGrade { return 100.0f; }

/**	 * Sets the configuration properties loaded from the config file *	 * @param props Properties list */	public void setConfigProperties(Properties props) { // Not needed for this analyzer }

/**	 * Returns a string representation of this object *	 * @return the string name of this analyzer */	public String toString { return "PercentageMethods"; } }

Step 2: Doing Something Useful
Now that we have the basics of our class together, let's add to the analyze method and do something useful with our new friend, the RootDoc reference.