1 package org.apache.maven.tools.plugin.extractor.annotations.converter;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import javax.inject.Inject;
23 import javax.inject.Named;
24 import javax.inject.Singleton;
25
26 import java.util.Map;
27
28 /*
29 * Licensed to the Apache Software Foundation (ASF) under one
30 * or more contributor license agreements. See the NOTICE file
31 * distributed with this work for additional information
32 * regarding copyright ownership. The ASF licenses this file
33 * to you under the Apache License, Version 2.0 (the
34 * "License"); you may not use this file except in compliance
35 * with the License. You may obtain a copy of the License at
36 *
37 * http://www.apache.org/licenses/LICENSE-2.0
38 *
39 * Unless required by applicable law or agreed to in writing,
40 * software distributed under the License is distributed on an
41 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
42 * KIND, either express or implied. See the License for the
43 * specific language governing permissions and limitations
44 * under the License.
45 */
46
47 import com.thoughtworks.qdox.model.DocletTag;
48 import org.apache.maven.tools.plugin.extractor.annotations.converter.tag.block.JavadocBlockTagToHtmlConverter;
49 import org.slf4j.Logger;
50 import org.slf4j.LoggerFactory;
51
52 /**
53 * Converts a given
54 * <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#block-tags">
55 * javadoc block taglet</a> to HTML.
56 * The implementations have a name equal to the supported doclet name.
57 * Must be called for each block tag individually.
58 */
59 @Named
60 @Singleton
61 public class JavadocBlockTagsToXhtmlConverter
62 {
63 private static final Logger LOG = LoggerFactory.getLogger( JavadocBlockTagsToXhtmlConverter.class );
64
65 private final JavadocInlineTagsToXhtmlConverter inlineTagsConverter;
66 private final Map<String, JavadocBlockTagToHtmlConverter> blockTagConverters;
67
68 @Inject
69 public JavadocBlockTagsToXhtmlConverter( JavadocInlineTagsToXhtmlConverter inlineTagsConverter,
70 Map<String, JavadocBlockTagToHtmlConverter> blockTagConverters )
71 {
72 this.inlineTagsConverter = inlineTagsConverter;
73 this.blockTagConverters = blockTagConverters;
74 }
75
76 public String convert( DocletTag docletTag, ConverterContext context )
77 {
78 return convert( docletTag.getName(), docletTag.getValue(), context );
79 }
80
81 public String convert( String name, String text, ConverterContext context )
82 {
83 JavadocBlockTagToHtmlConverter converter = blockTagConverters.get( name );
84 if ( converter == null )
85 {
86 return getOriginalTag( name, text ) + "<!-- unknown block tag '" + name + "' -->";
87 }
88 else
89 {
90 try
91 {
92 String convertedBlockTagValue = converter.convert( text, context );
93 return inlineTagsConverter.convert( convertedBlockTagValue, context );
94 }
95 catch ( Throwable t )
96 {
97 LOG.warn( "Error converting javadoc block tag '{}' in {}", name, context.getLocation(), t );
98 return getOriginalTag( name, text ) + "<!-- error processing javadoc tag '" + name + "': "
99 + t.getMessage() + "-->"; // leave original javadoc in place
100 }
101
102 }
103 }
104
105 private static String getOriginalTag( String name, String text )
106 {
107 return "@" + name + " " + text;
108 }
109 }