abstractoperatordocgenerator.java

著名的开源仿真软件yale

/*
 *  YALE - Yet Another Learning Environment
 *  Copyright (C) 2002, 2003
 *      Simon Fischer, Ralf Klinkenberg, Ingo Mierswa, 
 *          Katharina Morik, Oliver Ritthoff
 *      Artificial Intelligence Unit
 *      Computer Science Department
 *      University of Dortmund
 *      44221 Dortmund,  Germany
 *  email: [e-mail]
 *  web:   http://yale.cs.uni-dortmund.de/
 *
 *  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 2 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, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 *  USA.
 */
package edu.udo.cs.yale.doc;

import edu.udo.cs.yale.operator.Operator;
import edu.udo.cs.yale.operator.parameter.ParameterType;
import edu.udo.cs.yale.tools.Tools;
import edu.udo.cs.yale.tools.LogService;
import edu.udo.cs.yale.operator.Value;
import edu.udo.cs.yale.operator.IOObject;

import com.sun.javadoc.*;
import com.sun.tools.doclets.*;

import java.lang.reflect.Modifier;
import java.io.PrintWriter;
import java.io.IOException;
import java.util.Iterator;
import java.util.List;
import java.util.Collection;
import java.util.Map;
import java.util.HashMap;

public abstract class AbstractOperatorDocGenerator implements OperatorDocGenerator {

    public final static int OPERATOR              = 0; 
    public final static int OPERATOR_NAME         = 1; 
    public final static int PARAMETER_LIST        = 2; 
    public final static int PARAMETER_ITEM        = 3; 
    public final static int PARAMETER_NAME_REQ    = 4; 
    public final static int PARAMETER_NAME_OPT    = 5; 
    public final static int PARAMETER_DESCRIPTION = 6;  
    public final static int OPERATOR_DESCRIPTION  = 7;  
    public final static int INPUT_CLASSES_LIST    = 8;  
    public final static int OUTPUT_CLASSES_LIST   = 9;  
    public final static int IO_CLASS              = 10;
    public final static int VALUE_LIST            = 11;
    public final static int VALUE_ITEM            = 12;
    public final static int VALUE_NAME            = 13;
    public final static int VALUE_DESCRIPTION     = 14;
    public final static int INDEX_ENTRY           = 15;
    public final static int REFERENCE_SECTION     = 16;
    public final static int REFERENCE_ENTRY       = 17;

    private Map yaleTagletMap = new HashMap();

    /** Transform the HTML-comment to the respective output language. The class
     *  is only given for debugging purposes. */
    public abstract String transformHTMLJavadocComment(String comment, Class clazz);

    /** Replace any special characters by an escaped version. */
    public abstract String escape(String toEscape);

    public abstract String getOpenTag(int tagNo);
    public abstract String getCloseTag(int tagNo);
    public abstract String marginIcon(String iconName);

    public AbstractOperatorDocGenerator() {
	CiteTaglet.register(yaleTagletMap);
	MathTaglet.register(yaleTagletMap);
	RefTaglet.register(yaleTagletMap);
	XMLExampleTaglet.register(yaleTagletMap);
    }

    public void generateDoc(Operator op, RootDoc rootDoc, PrintWriter out) {
	ClassDoc opDoc = rootDoc.classNamed(op.getClass().getName());

	out.println(getOpenTag(OPERATOR));
	printTags(out, op.getOperatorDescription().getName(), OPERATOR_NAME);
	out.println();

	if (op.getOperatorDescription().getIconName() != null)
	    out.println(marginIcon(op.getOperatorDescription().getIconName()));

	Tag[] indexTags = opDoc.tags("yale.index");
	for (int i = 0; i < indexTags.length; i++) {
	    printTags(out, indexTags[i].text(), INDEX_ENTRY);
	}

	Class[] input = op.getInputClasses();
	if ((input != null) && (input.length > 0)) {
	    out.println(getOpenTag(INPUT_CLASSES_LIST));
	    for (int i = 0; i < input.length; i++) {
		printTags(out, Tools.classNameWOPackage(input[i]), IO_CLASS);
		out.println();
	    }
	    out.println(getCloseTag(INPUT_CLASSES_LIST));
	}

	Class[] output = op.getOutputClasses();
	if ((output != null) && (output.length > 0)) {
	    out.println(getOpenTag(OUTPUT_CLASSES_LIST));
	    for (int i = 0; i < output.length; i++) {
		printTags(out, Tools.classNameWOPackage(output[i]), IO_CLASS);
		out.println();
	    }
	    out.println(getCloseTag(OUTPUT_CLASSES_LIST));
	}

	List parameters = op.getParameterTypes();
	if (parameters.size() > 0) {
	    out.println(getOpenTag(PARAMETER_LIST));
	    Iterator i = parameters.iterator();
	    while (i.hasNext()) {
		ParameterType type = (ParameterType)i.next();
		out.print(getOpenTag(PARAMETER_ITEM));
		if (type.isOptional()) {
		    printTags(out, type.getKey(), PARAMETER_NAME_OPT);
		} else { 
		    printTags(out, type.getKey(), PARAMETER_NAME_REQ);
		}
		printTags(out, type.getDescription() + " (" + type.getRange() + ")", PARAMETER_DESCRIPTION);
		out.println(getCloseTag(PARAMETER_ITEM));
	    }
	    out.println(getCloseTag(PARAMETER_LIST));
	}

	Collection values = op.getValues();
	if (values.size() > 0) {
	    out.println(getOpenTag(VALUE_LIST));
	    Iterator i = values.iterator();
	    while (i.hasNext()) {
		Value value = (Value)i.next();
		//if (!value.isDocumented()) continue;
		out.print(getOpenTag(VALUE_ITEM));
		printTags(out, value.getKey(), VALUE_NAME);
		printTags(out, value.getDescription(), VALUE_DESCRIPTION);
		out.println(getCloseTag(VALUE_ITEM));
	    }
	    out.println(getCloseTag(VALUE_LIST));
	}


	StringBuffer classComment = new StringBuffer();
	Tag[] inlineTags = opDoc.inlineTags();
	for (int i = 0; i < inlineTags.length; i++) {
	    if (inlineTags[i] instanceof SeeTag) {
		try {
		    Class referencedClass = Class.forName(((SeeTag)inlineTags[i]).referencedClass().qualifiedName());
		    if (Operator.class.isAssignableFrom(referencedClass)) {
			if (java.lang.reflect.Modifier.isAbstract(referencedClass.getModifiers())) {
			    classComment.append("\\op{"+Tools.classNameWOPackage(referencedClass)+"}");
			} else {
			    Operator refOp = (Operator)referencedClass.newInstance();
			    classComment.append("\\refop{"+refOp.getOperatorDescription().getName()+"}");
			}
		    } else if (IOObject.class.isAssignableFrom(referencedClass)) {
			classComment.append("\\ioobj{"+Tools.classNameWOPackage(referencedClass)+"}");
		    } else {
			classComment.append("\\java{"+Tools.classNameWOPackage(referencedClass)+"}");
		    }
		} catch (Throwable e) {
		    LogService.logMessage("In see tag '"+inlineTags[i]+"' of "+op.getClass().getName()+": " + e, LogService.ERROR);
		}		
	    } else {
		Taglet taglet = (Taglet)yaleTagletMap.get(inlineTags[i].name().substring(1));
		if (taglet instanceof TexTaglet) {
		    classComment.append(((TexTaglet)taglet).toTex(inlineTags[i]));
		} else {
		    classComment.append(escape(inlineTags[i].text()));
		}
	    }
	}

  	out.println(getOpenTag(OPERATOR_DESCRIPTION)+
		    transformHTMLJavadocComment(classComment.toString(), op.getClass())+
  		    getCloseTag(OPERATOR_DESCRIPTION));
  	out.println();

	Tag[] citeTags = opDoc.tags("yale.cite");
	if (citeTags.length > 0) 
	    out.println(getOpenTag(REFERENCE_SECTION));
	for (int i = 0; i < citeTags.length; i++) {
	    printTags(out, citeTags[i].text(), REFERENCE_ENTRY);
	}

	out.println(getCloseTag(OPERATOR));
    } 

    private void printTags(PrintWriter out, String text, int tagNo) {
	out.print(getOpenTag(tagNo) + escape(text) + getCloseTag(tagNo));
    }

}