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}