001package org.apache.maven.tools.plugin.extractor.annotations.converter;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import javax.inject.Inject;
023import javax.inject.Named;
024import javax.inject.Singleton;
025
026import java.util.Map;
027
028/*
029 * Licensed to the Apache Software Foundation (ASF) under one
030 * or more contributor license agreements.  See the NOTICE file
031 * distributed with this work for additional information
032 * regarding copyright ownership.  The ASF licenses this file
033 * to you under the Apache License, Version 2.0 (the
034 * "License"); you may not use this file except in compliance
035 * with the License.  You may obtain a copy of the License at
036 *
037 *   http://www.apache.org/licenses/LICENSE-2.0
038 *
039 * Unless required by applicable law or agreed to in writing,
040 * software distributed under the License is distributed on an
041 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
042 * KIND, either express or implied.  See the License for the
043 * specific language governing permissions and limitations
044 * under the License.
045 */
046
047import com.thoughtworks.qdox.model.DocletTag;
048import org.apache.maven.tools.plugin.extractor.annotations.converter.tag.block.JavadocBlockTagToHtmlConverter;
049import org.slf4j.Logger;
050import org.slf4j.LoggerFactory;
051
052/**
053 * Converts a given 
054 * <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#block-tags">
055 * javadoc block taglet</a> to HTML.
056 * The implementations have a name equal to the supported doclet name.
057 * Must be called for each block tag individually.
058 */
059@Named
060@Singleton
061public class JavadocBlockTagsToXhtmlConverter
062{
063    private static final Logger LOG = LoggerFactory.getLogger( JavadocBlockTagsToXhtmlConverter.class );
064
065    private final JavadocInlineTagsToXhtmlConverter inlineTagsConverter;
066    private final Map<String, JavadocBlockTagToHtmlConverter> blockTagConverters;
067
068    @Inject
069    public JavadocBlockTagsToXhtmlConverter( JavadocInlineTagsToXhtmlConverter inlineTagsConverter,
070                                             Map<String, JavadocBlockTagToHtmlConverter> blockTagConverters )
071    {
072        this.inlineTagsConverter = inlineTagsConverter;
073        this.blockTagConverters = blockTagConverters;
074    }
075
076    public String convert( DocletTag docletTag, ConverterContext context )
077    {
078        return convert( docletTag.getName(), docletTag.getValue(), context );
079    }
080
081    public String convert( String name, String text, ConverterContext context )
082    {
083        JavadocBlockTagToHtmlConverter converter = blockTagConverters.get( name );
084        if ( converter == null )
085        {
086            return getOriginalTag( name, text ) + "<!-- unknown block tag '" + name + "' -->";
087        }
088        else
089        {
090            try
091            {
092                String convertedBlockTagValue = converter.convert( text, context );
093                return inlineTagsConverter.convert( convertedBlockTagValue, context );
094            }
095            catch ( Throwable t )
096            {
097                LOG.warn( "Error converting javadoc block tag '{}' in {}", name, context.getLocation(), t );
098                return getOriginalTag( name, text ) + "<!-- error processing javadoc tag '" + name + "': "
099                + 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}