This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j-tools.git
commit 290e3a5d7748449bdc12841ea179d58b481b84db Author: Volkan Yazıcı <[email protected]> AuthorDate: Tue Mar 12 20:32:14 2024 +0100 Improve FQCN derivation from `{@link` for package locals --- .../processor/AbstractAsciiDocTreeVisitor.java | 37 +++++++++++++++------- .../docgen/processor/DescriptorGenerator.java | 34 +++++++++++++++----- .../AsciiDocConverterTest/JavadocExample.adoc | 2 +- .../DescriptorGeneratorTest/expected-plugins.xml | 6 ++-- 4 files changed, 55 insertions(+), 24 deletions(-) diff --git a/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciiDocTreeVisitor.java b/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciiDocTreeVisitor.java index 642d283..38b6928 100644 --- a/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciiDocTreeVisitor.java +++ b/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciiDocTreeVisitor.java @@ -241,23 +241,36 @@ abstract class AbstractAsciiDocTreeVisitor extends SimpleDocTreeVisitor<Void, As return data.qualifiedClassName + referenceSignature; } - // If it is of type {@link Foo#bar}` + // Determine class and method parts of the reference signature final int methodSplitterIndex = referenceSignature.indexOf('#'); + final String classSignature; + final String methodSignature; if (methodSplitterIndex > 0) { - final String classNamePart = referenceSignature.substring(0, methodSplitterIndex); - @Nullable final String qualifiedClassName = data.imports.get(classNamePart); - if (qualifiedClassName == null) { - return referenceSignature; - } - final String methodPart = referenceSignature.substring(methodSplitterIndex); - return qualifiedClassName + methodPart; + classSignature = referenceSignature.substring(0, methodSplitterIndex); + methodSignature = referenceSignature.substring(methodSplitterIndex); + } else { + classSignature = referenceSignature; + methodSignature = ""; + } + + // If it is an imported class + @Nullable final String importedClassFqcn = data.imports.get(classSignature); + if (importedClassFqcn != null) { + return importedClassFqcn + methodSignature; } - // Otherwise - else { - @Nullable final String qualifiedClassName = data.imports.get(referenceSignature); - return qualifiedClassName != null ? qualifiedClassName : referenceSignature; + // If it is a `java.lang` class + try { + final String qualifiedClassName = "java.lang." + classSignature; + Class.forName(qualifiedClassName); + return qualifiedClassName + methodSignature; + } catch (final ClassNotFoundException ignored) { + // Do nothing } + + // Otherwise it is a package-local class + final String packageName = data.qualifiedClassName.substring(0, data.qualifiedClassName.lastIndexOf('.')); + return packageName + '.' + classSignature + methodSignature; } private static String linkLabelToAsciiDoc(final LinkTree node) { diff --git a/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/DescriptorGenerator.java b/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/DescriptorGenerator.java index 9cbffc7..49e6014 100644 --- a/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/DescriptorGenerator.java +++ b/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/DescriptorGenerator.java @@ -289,7 +289,11 @@ public class DescriptorGenerator extends AbstractProcessor { } } - private void populateType(final QualifiedNameable element, final ElementImports imports, final String qualifiedClassName, final Type docgenType) { + private void populateType( + final QualifiedNameable element, + final ElementImports imports, + final String qualifiedClassName, + final Type docgenType) { // Class name docgenType.setClassName(element.getQualifiedName().toString()); // Description @@ -315,7 +319,8 @@ public class DescriptorGenerator extends AbstractProcessor { } } - private Map<String, String> getParameterDescriptions(final Element element, final ElementImports imports, final String qualifiedClassName) { + private Map<String, String> getParameterDescriptions( + final Element element, final ElementImports imports, final String qualifiedClassName) { final Map<String, String> descriptions = new HashMap<>(); final DocCommentTree docCommentTree = docTrees.getDocCommentTree(element); if (docCommentTree != null) { @@ -332,7 +337,8 @@ public class DescriptorGenerator extends AbstractProcessor { @Override public Void visitParam(final ParamTree paramTree, final Map<String, String> descriptions) { final String name = paramTree.getName().getName().toString(); - descriptions.put(name, defaultString(converter.toAsciiDoc(paramTree, imports, qualifiedClassName))); + descriptions.put( + name, defaultString(converter.toAsciiDoc(paramTree, imports, qualifiedClassName))); return null; } }, @@ -351,13 +357,15 @@ public class DescriptorGenerator extends AbstractProcessor { for (final Element member : element.getEnclosedElements()) { if (annotations.hasFactoryAnnotation(member) && member instanceof ExecutableElement) { final ExecutableElement executable = (ExecutableElement) member; - final Map<String, String> descriptions = getParameterDescriptions(executable, imports, qualifiedClassName); + final Map<String, String> descriptions = + getParameterDescriptions(executable, imports, qualifiedClassName); final List<? extends VariableElement> parameters = executable.getParameters(); if (parameters.isEmpty()) { // We have a builder final TypeElement returnType = getReturnType(executable); if (returnType != null) { - populateConfigurationProperties(imports, qualifiedClassName, getAllMembers(returnType), descriptions, pluginType); + populateConfigurationProperties( + imports, qualifiedClassName, getAllMembers(returnType), descriptions, pluginType); } else { messager.printMessage( Diagnostic.Kind.WARNING, @@ -414,7 +422,10 @@ public class DescriptorGenerator extends AbstractProcessor { @Nullable private Description createDescription( - final Element element, ElementImports imports, final String qualifiedClassName, final @Nullable String fallbackDescriptionText) { + final Element element, + ElementImports imports, + final String qualifiedClassName, + final @Nullable String fallbackDescriptionText) { @Nullable String descriptionText = converter.toAsciiDoc(element, imports, qualifiedClassName); if (StringUtils.isBlank(descriptionText)) { if (StringUtils.isBlank(fallbackDescriptionText)) { @@ -430,7 +441,11 @@ public class DescriptorGenerator extends AbstractProcessor { } private PluginAttribute createPluginAttribute( - final Element element, final ElementImports imports, final String qualifiedClassName, final String description, final String specifiedName) { + final Element element, + final ElementImports imports, + final String qualifiedClassName, + final String description, + final String specifiedName) { final PluginAttribute attribute = new PluginAttribute(); // Name attribute.setName(specifiedName.isEmpty() ? getAttributeOrPropertyName(element) : specifiedName); @@ -457,7 +472,10 @@ public class DescriptorGenerator extends AbstractProcessor { } private PluginElement createPluginElement( - final Element element, final ElementImports imports, final String qualifiedClassName, final String description) { + final Element element, + final ElementImports imports, + final String qualifiedClassName, + final String description) { final PluginElement pluginElement = new PluginElement(); // Type and multiplicity final TypeMirror elementType = getMemberType(element); diff --git a/log4j-docgen/src/test/resources/AsciiDocConverterTest/JavadocExample.adoc b/log4j-docgen/src/test/resources/AsciiDocConverterTest/JavadocExample.adoc index 85e83b3..e97c87a 100644 --- a/log4j-docgen/src/test/resources/AsciiDocConverterTest/JavadocExample.adoc +++ b/log4j-docgen/src/test/resources/AsciiDocConverterTest/JavadocExample.adoc @@ -16,7 +16,7 @@ limitations under the License. //// Example of JavaDoc to AsciiDoc conversion -Reference to method in the default namespace: apiref:String#value()[value method] +Reference to method in the default namespace: apiref:java.lang.String#value()[value method] Reference to imported class: apiref:javax.tools.Diagnostic[] diff --git a/log4j-docgen/src/test/resources/DescriptorGeneratorTest/expected-plugins.xml b/log4j-docgen/src/test/resources/DescriptorGeneratorTest/expected-plugins.xml index ecf315e..f6dd170 100644 --- a/log4j-docgen/src/test/resources/DescriptorGeneratorTest/expected-plugins.xml +++ b/log4j-docgen/src/test/resources/DescriptorGeneratorTest/expected-plugins.xml @@ -120,8 +120,8 @@ It has the following characteristics: It also implements: -* apiref:Appender[], -* apiref:BaseAppender[]</description> +* apiref:example.Appender[], +* apiref:example.BaseAppender[]</description> </plugin> <plugin name="MyLayout" className="example.MyOldLayout"> <supertypes> @@ -160,7 +160,7 @@ It also implements: <description>A `short` attribute.</description> </attribute> <attribute name="stringAttr" required="true"> - <description>A apiref:String[] attribute.</description> + <description>A apiref:java.lang.String[] attribute.</description> </attribute> </attributes> <elements>
