| /* |
| * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code 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 |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.codemodel.internal; |
| |
| import java.util.HashMap; |
| import java.util.Map; |
| |
| /** |
| * JavaDoc comment. |
| * |
| * <p> |
| * A javadoc comment consists of multiple parts. There's the main part (that comes the first in |
| * in the comment section), then the parameter parts (@param), the return part (@return), |
| * and the throws parts (@throws). |
| * |
| * TODO: it would be nice if we have JComment class and we can derive this class from there. |
| */ |
| public class JDocComment extends JCommentPart implements JGenerable { |
| |
| private static final long serialVersionUID = 1L; |
| |
| /** list of @param tags */ |
| private final Map<String,JCommentPart> atParams = new HashMap<String,JCommentPart>(); |
| |
| /** list of xdoclets */ |
| private final Map<String,Map<String,String>> atXdoclets = new HashMap<String,Map<String,String>>(); |
| |
| /** list of @throws tags */ |
| private final Map<JClass,JCommentPart> atThrows = new HashMap<JClass,JCommentPart>(); |
| |
| /** |
| * The @return tag part. |
| */ |
| private JCommentPart atReturn = null; |
| |
| /** The @deprecated tag */ |
| private JCommentPart atDeprecated = null; |
| |
| private final JCodeModel owner; |
| |
| |
| public JDocComment(JCodeModel owner) { |
| this.owner = owner; |
| } |
| |
| public JDocComment append(Object o) { |
| add(o); |
| return this; |
| } |
| |
| /** |
| * Append a text to a @param tag to the javadoc |
| */ |
| public JCommentPart addParam( String param ) { |
| JCommentPart p = atParams.get(param); |
| if(p==null) |
| atParams.put(param,p=new JCommentPart()); |
| return p; |
| } |
| |
| /** |
| * Append a text to an @param tag. |
| */ |
| public JCommentPart addParam( JVar param ) { |
| return addParam( param.name() ); |
| } |
| |
| |
| /** |
| * add an @throws tag to the javadoc |
| */ |
| public JCommentPart addThrows( Class<? extends Throwable> exception ) { |
| return addThrows( owner.ref(exception) ); |
| } |
| |
| /** |
| * add an @throws tag to the javadoc |
| */ |
| public JCommentPart addThrows( JClass exception ) { |
| JCommentPart p = atThrows.get(exception); |
| if(p==null) |
| atThrows.put(exception,p=new JCommentPart()); |
| return p; |
| } |
| |
| /** |
| * Appends a text to @return tag. |
| */ |
| public JCommentPart addReturn() { |
| if(atReturn==null) |
| atReturn = new JCommentPart(); |
| return atReturn; |
| } |
| |
| /** |
| * add an @deprecated tag to the javadoc, with the associated message. |
| */ |
| public JCommentPart addDeprecated() { |
| if(atDeprecated==null) |
| atDeprecated = new JCommentPart(); |
| return atDeprecated; |
| } |
| |
| /** |
| * add an xdoclet. |
| */ |
| public Map<String,String> addXdoclet(String name) { |
| Map<String,String> p = atXdoclets.get(name); |
| if(p==null) |
| atXdoclets.put(name,p=new HashMap<String,String>()); |
| return p; |
| } |
| |
| /** |
| * add an xdoclet. |
| */ |
| public Map<String,String> addXdoclet(String name, Map<String,String> attributes) { |
| Map<String,String> p = atXdoclets.get(name); |
| if(p==null) |
| atXdoclets.put(name,p=new HashMap<String,String>()); |
| p.putAll(attributes); |
| return p; |
| } |
| |
| /** |
| * add an xdoclet. |
| */ |
| public Map<String,String> addXdoclet(String name, String attribute, String value) { |
| Map<String,String> p = atXdoclets.get(name); |
| if(p==null) |
| atXdoclets.put(name,p=new HashMap<String,String>()); |
| p.put(attribute, value); |
| return p; |
| } |
| |
| public void generate(JFormatter f) { |
| // I realized that we can't use StringTokenizer because |
| // this will recognize multiple \n as one token. |
| |
| f.p("/**").nl(); |
| |
| format(f," * "); |
| |
| f.p(" * ").nl(); |
| for (Map.Entry<String,JCommentPart> e : atParams.entrySet()) { |
| f.p(" * @param ").p(e.getKey()).nl(); |
| e.getValue().format(f,INDENT); |
| } |
| if( atReturn != null ) { |
| f.p(" * @return").nl(); |
| atReturn.format(f,INDENT); |
| } |
| for (Map.Entry<JClass,JCommentPart> e : atThrows.entrySet()) { |
| f.p(" * @throws ").t(e.getKey()).nl(); |
| e.getValue().format(f,INDENT); |
| } |
| if( atDeprecated != null ) { |
| f.p(" * @deprecated").nl(); |
| atDeprecated.format(f,INDENT); |
| } |
| for (Map.Entry<String,Map<String,String>> e : atXdoclets.entrySet()) { |
| f.p(" * @").p(e.getKey()); |
| if (e.getValue() != null) { |
| for (Map.Entry<String,String> a : e.getValue().entrySet()) { |
| f.p(" ").p(a.getKey()).p("= \"").p(a.getValue()).p("\""); |
| } |
| } |
| f.nl(); |
| } |
| f.p(" */").nl(); |
| } |
| |
| private static final String INDENT = " * "; |
| } |