vy commented on code in PR #101: URL: https://github.com/apache/logging-log4j-tools/pull/101#discussion_r1478880319
########## log4j-docgen/pom.xml: ########## @@ -27,6 +27,7 @@ <artifactId>log4j-docgen</artifactId> <properties> + <maven.compiler.release>17</maven.compiler.release> Review Comment: Why is this necessary? ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciidocConverter.java: ########## @@ -0,0 +1,86 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.DocTreeVisitor; +import com.sun.source.doctree.ParamTree; +import com.sun.source.util.DocTrees; +import javax.lang.model.element.Element; + +/** + * Converts a {@link DocCommentTree} into AsciiDoc text. + */ +class AsciidocConverter { + + private static final DocTreeVisitor<Void, AsciidocData> DOC_COMMENT_TREE_VISITOR = new DocCommentTreeVisitor(); + private static final DocTreeVisitor<Void, AsciidocData> PARAM_TREE_VISITOR = new ParamTreeVisitor(); + + private final DocTrees docTrees; + + AsciidocConverter(final DocTrees docTrees) { + this.docTrees = docTrees; + } + + public String toAsciiDoc(final Element element) { + final DocCommentTree tree = docTrees.getDocCommentTree(element); + return tree != null ? toAsciiDoc(tree) : null; + } + + public String toAsciiDoc(final DocCommentTree tree) { + final AsciidocData data = new AsciidocData(); + tree.accept(DOC_COMMENT_TREE_VISITOR, data); + return data.getDocument().convert(); + } + + public String toAsciiDoc(final ParamTree tree) { + final AsciidocData data = new AsciidocData(); + tree.accept(PARAM_TREE_VISITOR, data); + return data.getDocument().convert(); + } + + private static class DocCommentTreeVisitor extends AbstractAsciidocTreeVisitor { Review Comment: ```suggestion private static final class DocCommentTreeVisitor extends AbstractAsciidocTreeVisitor { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciidocTreeVisitor.java: ########## @@ -0,0 +1,233 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import static org.apache.commons.lang3.StringUtils.substringBefore; + +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.EndElementTree; +import com.sun.source.doctree.LinkTree; +import com.sun.source.doctree.LiteralTree; +import com.sun.source.doctree.StartElementTree; +import com.sun.source.doctree.TextTree; +import com.sun.source.util.SimpleDocTreeVisitor; +import java.util.ArrayList; +import org.apache.commons.lang3.StringUtils; +import org.apache.logging.log4j.docgen.processor.internal.BlockImpl; +import org.apache.logging.log4j.docgen.processor.internal.CellImpl; +import org.apache.logging.log4j.docgen.processor.internal.ListImpl; +import org.apache.logging.log4j.docgen.processor.internal.ListItemImpl; +import org.apache.logging.log4j.docgen.processor.internal.RowImpl; +import org.apache.logging.log4j.docgen.processor.internal.TableImpl; +import org.asciidoctor.ast.Block; +import org.asciidoctor.ast.Cell; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.List; +import org.asciidoctor.ast.ListItem; +import org.asciidoctor.ast.Row; +import org.asciidoctor.ast.Section; +import org.asciidoctor.ast.StructuralNode; +import org.asciidoctor.ast.Table; + +class AbstractAsciidocTreeVisitor extends SimpleDocTreeVisitor<Void, AsciidocData> { + + private static void appendSentences(final String text, final AsciidocData data) { + final String body = StringUtils.normalizeSpace(text); + final String[] sentences = body.split("(?<=\\w{2}[.!?])", -1); + // Full sentences + for (int i = 0; i < sentences.length - 1; i++) { + data.appendWords(sentences[i].strip()); + data.newLine(); + } + // Partial sentence + data.appendWords(sentences[sentences.length - 1].strip()); + } + + @Override + public Void visitStartElement(final StartElementTree node, final AsciidocData data) { + final String elementName = node.getName().toString(); + switch (elementName) { + case "p": + data.newParagraph(); + break; + case "ol": + // Nested list without a first paragraph + if (data.getCurrentNode() instanceof ListItem) { + data.newParagraph(); + } + data.pushChildNode(ListImpl::new).setContext(ListImpl.ORDERED_LIST_CONTEXT); + break; + case "ul": + // Nested list without a first paragraph + if (data.getCurrentNode() instanceof ListItem) { + data.newParagraph(); + } + data.pushChildNode(ListImpl::new).setContext(ListImpl.UNORDERED_LIST_CONTEXT); + break; + case "li": + if (!(data.getCurrentNode() instanceof List)) { + throw new IllegalArgumentException("A <li> tag must be a child of a <ol> or <ul> tag."); + } + data.pushChildNode(ListItemImpl::new); + break; + case "h1": + case "h2": + case "h3": + case "h4": + case "h5": + case "h6": + // Flush the current paragraph + data.newParagraph(); + StructuralNode currentNode; + // Remove other types of nodes from stack + while ((currentNode = data.getCurrentNode()) != null + && !(currentNode instanceof Section || currentNode instanceof Document)) { + data.popNode(); + } + break; + case "table": + data.pushChildNode(TableImpl::new); + break; + case "tr": + break; + case "th": + data.pushChildNode(CellImpl::new).setContext(CellImpl.HEADER_CONTEXT); + break; + case "td": + data.pushChildNode(CellImpl::new); + break; + case "pre": + data.newParagraph(); + final Block currentParagraph = data.getCurrentParagraph(); + currentParagraph.setContext(BlockImpl.LISTING_CONTEXT); + currentParagraph.setStyle(BlockImpl.SOURCE_STYLE); + break; + default: + } + return super.visitStartElement(node, data); + } + + @Override + public Void visitEndElement(final EndElementTree node, final AsciidocData data) { + final String elementName = node.getName().toString(); + switch (elementName) { + case "p": + // Ignore closing tags. + break; + case "ol": + case "ul": + case "li": + case "table": + case "th": + case "td": + data.popNode(); + break; + case "h1": + case "h2": + case "h3": + case "h4": + case "h5": + case "h6": + // Only flush the current line + if (!data.getCurrentLine().isEmpty()) { + data.newLine(); + } + // The current paragraph contains the title + // We retrieve the text and empty the paragraph + final Block currentParagraph = data.getCurrentParagraph(); + final String title = StringUtils.normalizeSpace(currentParagraph.convert()); + currentParagraph.setLines(new ArrayList<>()); + + // There should be no <h1> tags + final int newLevel = "h1".equals(elementName) ? 2 : elementName.charAt(1) - '0'; + data.setCurrentSectionLevel(newLevel); + data.getCurrentNode().setTitle(title); + break; + case "pre": + data.newParagraph(); + break; + case "tr": + // We group the new cells into a row + final Table table = (Table) data.getCurrentNode(); + final java.util.List<StructuralNode> cells = table.getBlocks(); + // First index of the row + int idx = 0; + for (final Row row : table.getHeader()) { + idx += row.getCells().size(); + } + for (final Row row : table.getBody()) { + idx += row.getCells().size(); + } + final Row row = new RowImpl(); + String context = CellImpl.BODY_CONTEXT; + for (int i = idx; i < table.getBlocks().size(); i++) { + final StructuralNode cell = cells.get(i); + context = cell.getContext(); + if (cell instanceof Cell) { + row.getCells().add((Cell) cell); + } + } + if (CellImpl.HEADER_CONTEXT.equals(context)) { + table.getHeader().add(row); + } else { + table.getBody().add(row); + } + break; + default: + } + return super.visitEndElement(node, data); + } + + @Override + public Void visitLink(final LinkTree node, final AsciidocData data) { + final String className = substringBefore(node.getReference().getSignature(), '#'); + final String simpleName = StringUtils.substringAfterLast(className, '.'); + if (!data.getCurrentLine().isEmpty()) { + data.append(" "); + } + data.append("xref:") + .append(className) + .append(".adoc[") + .append(simpleName) + .append("]"); + return super.visitLink(node, data); + } + + @Override + public Void visitLiteral(final LiteralTree node, final AsciidocData data) { + if (node.getKind() == DocTree.Kind.CODE) { + if (!data.getCurrentLine().isEmpty()) { + data.append(" "); + } + data.append("`").append(node.getBody().getBody()).append("`"); Review Comment: I think the following cases are not handled: ``` <code>foo`</code> (needs to be represented with `++foo`++`) <code>foo</code>bar (converting this to `foo`bar won't work, it needs to be ``foo``bar) ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/ListItemImpl.java: ########## @@ -0,0 +1,74 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.ContentNode; +import org.asciidoctor.ast.ListItem; +import org.asciidoctor.ast.StructuralNode; + +public class ListItemImpl extends StructuralNodeImpl implements ListItem { Review Comment: ```suggestion public final class ListItemImpl extends StructuralNodeImpl implements ListItem { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/DocumentImpl.java: ########## @@ -0,0 +1,123 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.List; +import java.util.Map; +import org.apache.commons.lang3.StringUtils; +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.Author; +import org.asciidoctor.ast.Catalog; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.RevisionInfo; +import org.asciidoctor.ast.StructuralNode; +import org.asciidoctor.ast.Title; + +public class DocumentImpl extends StructuralNodeImpl implements Document { + + public DocumentImpl() { + super(null); + } + + @Override + public void formatTo(final StringBuilder buffer) { + if (!StringUtils.isBlank(getTitle())) { + buffer.append("= ").append(getTitle()).append("\n\n"); + } + boolean first = true; + for (final StructuralNode node : getBlocks()) { + if (!first) { + buffer.append('\n'); + } else { + first = false; + } + if (node instanceof final StringBuilderFormattable formattable) { Review Comment: Mind explaining how can we receive an instance of `StringBuilderFormattable`? I was under the impression we are only dealing with ASTs. ########## log4j-docgen/pom.xml: ########## @@ -38,11 +39,38 @@ <scope>provided</scope> </dependency> + <dependency> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctorj-api</artifactId> + <version>3.0.0-alpha.2</version> Review Comment: Nit: I prefer a `asciidoctorj.version` property in _this_ `pom.xml` file. ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciidocTreeVisitor.java: ########## @@ -0,0 +1,233 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import static org.apache.commons.lang3.StringUtils.substringBefore; + +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.EndElementTree; +import com.sun.source.doctree.LinkTree; +import com.sun.source.doctree.LiteralTree; +import com.sun.source.doctree.StartElementTree; +import com.sun.source.doctree.TextTree; +import com.sun.source.util.SimpleDocTreeVisitor; +import java.util.ArrayList; +import org.apache.commons.lang3.StringUtils; +import org.apache.logging.log4j.docgen.processor.internal.BlockImpl; +import org.apache.logging.log4j.docgen.processor.internal.CellImpl; +import org.apache.logging.log4j.docgen.processor.internal.ListImpl; +import org.apache.logging.log4j.docgen.processor.internal.ListItemImpl; +import org.apache.logging.log4j.docgen.processor.internal.RowImpl; +import org.apache.logging.log4j.docgen.processor.internal.TableImpl; +import org.asciidoctor.ast.Block; +import org.asciidoctor.ast.Cell; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.List; +import org.asciidoctor.ast.ListItem; +import org.asciidoctor.ast.Row; +import org.asciidoctor.ast.Section; +import org.asciidoctor.ast.StructuralNode; +import org.asciidoctor.ast.Table; + +class AbstractAsciidocTreeVisitor extends SimpleDocTreeVisitor<Void, AsciidocData> { Review Comment: Any particular reasons on why this class is not `abstract`? ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciidocData.java: ########## Review Comment: Shouldn't all the `public` methods be package-local instead? ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciidocConverter.java: ########## @@ -0,0 +1,86 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.DocTreeVisitor; +import com.sun.source.doctree.ParamTree; +import com.sun.source.util.DocTrees; +import javax.lang.model.element.Element; + +/** + * Converts a {@link DocCommentTree} into AsciiDoc text. + */ +class AsciidocConverter { Review Comment: ```suggestion final class AsciidocConverter { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciidocConverter.java: ########## @@ -0,0 +1,86 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.DocTreeVisitor; +import com.sun.source.doctree.ParamTree; +import com.sun.source.util.DocTrees; +import javax.lang.model.element.Element; + +/** + * Converts a {@link DocCommentTree} into AsciiDoc text. + */ +class AsciidocConverter { + + private static final DocTreeVisitor<Void, AsciidocData> DOC_COMMENT_TREE_VISITOR = new DocCommentTreeVisitor(); + private static final DocTreeVisitor<Void, AsciidocData> PARAM_TREE_VISITOR = new ParamTreeVisitor(); + + private final DocTrees docTrees; + + AsciidocConverter(final DocTrees docTrees) { + this.docTrees = docTrees; + } + + public String toAsciiDoc(final Element element) { + final DocCommentTree tree = docTrees.getDocCommentTree(element); + return tree != null ? toAsciiDoc(tree) : null; + } + + public String toAsciiDoc(final DocCommentTree tree) { + final AsciidocData data = new AsciidocData(); + tree.accept(DOC_COMMENT_TREE_VISITOR, data); + return data.getDocument().convert(); + } + + public String toAsciiDoc(final ParamTree tree) { + final AsciidocData data = new AsciidocData(); + tree.accept(PARAM_TREE_VISITOR, data); + return data.getDocument().convert(); + } + + private static class DocCommentTreeVisitor extends AbstractAsciidocTreeVisitor { + @Override + public Void visitDocComment(final DocCommentTree node, final AsciidocData data) { + // Summary block wrapped in a new paragraph. + for (final DocTree docTree : node.getFirstSentence()) { + docTree.accept(this, data); + } + data.newParagraph(); + // Body + for (final DocTree docTree : node.getBody()) { + docTree.accept(this, data); + } + // Flushes the last paragraph + data.newParagraph(); + return super.visitDocComment(node, data); + } + } + + private static class ParamTreeVisitor extends AbstractAsciidocTreeVisitor { Review Comment: ```suggestion private static final class ParamTreeVisitor extends AbstractAsciidocTreeVisitor { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/ContentNodeImpl.java: ########## @@ -0,0 +1,190 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.List; +import java.util.Map; +import org.asciidoctor.ast.ContentNode; +import org.asciidoctor.ast.Document; + +public abstract class ContentNodeImpl implements ContentNode { Review Comment: ```suggestion abstract class ContentNodeImpl implements ContentNode { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AsciidocData.java: ########## @@ -0,0 +1,149 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor; + +import java.util.EmptyStackException; +import java.util.function.Function; +import org.apache.logging.log4j.docgen.processor.internal.BlockImpl; +import org.apache.logging.log4j.docgen.processor.internal.DocumentImpl; +import org.apache.logging.log4j.docgen.processor.internal.SectionImpl; +import org.asciidoctor.ast.Block; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.StructuralNode; + +class AsciidocData { Review Comment: ```suggestion final class AsciidocData { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/DocumentImpl.java: ########## @@ -0,0 +1,123 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.List; +import java.util.Map; +import org.apache.commons.lang3.StringUtils; +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.Author; +import org.asciidoctor.ast.Catalog; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.RevisionInfo; +import org.asciidoctor.ast.StructuralNode; +import org.asciidoctor.ast.Title; + +public class DocumentImpl extends StructuralNodeImpl implements Document { Review Comment: ```suggestion public final class DocumentImpl extends StructuralNodeImpl implements Document { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/ListImpl.java: ########## @@ -0,0 +1,96 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.Objects; +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.ContentNode; +import org.asciidoctor.ast.List; +import org.asciidoctor.ast.ListItem; +import org.asciidoctor.ast.StructuralNode; + +public class ListImpl extends StructuralNodeImpl implements List { Review Comment: ```suggestion public final class ListImpl extends StructuralNodeImpl implements List { ``` ########## log4j-docgen/src/test/it/example/JavadocExample.java: ########## Review Comment: Could you add tests for the following too, please? ``` <code>foo</code> <code>foo`</code> <code>`foo</code> <code>`foo`</code> <code>foo</code>bar <code>foo`</code>bar <code>`foo</code>bar <code>`foo`</code>bar <code>foo``</code> <code>``foo</code> <code>``foo``</code> <code>foo</code>bar <code>foo``</code>bar <code>``foo</code>bar <code>``foo``</code>bar {@code foo} {@code foo`} {@code `foo} {@code `foo`} {@code foo}bar {@code foo`}bar {@code `foo}bar {@code `foo`}bar {@code foo``} {@code ``foo} {@code ``foo``} {@code foo}bar {@code foo``}bar {@code ``foo}bar {@code ``foo``}bar <pre> breaking the `source` block: ---- 've just done it </pre> <pre>[<![CDATA[ <code>this should not get converted</code> {@code what about this?} ]]></pre> <ul> <li>item without ending <li>- breaking the item</li> <li>* breaking the item</li> <li>. breaking the item</li> </ul> ``` Note that we don't need to accept every broken or non-idiomatic javadoc. Above are just certain corner cases I am able to think of. We can also choose to rewrite the source javadoc causing the issue. ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/RowImpl.java: ########## @@ -0,0 +1,32 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.ArrayList; +import java.util.List; +import org.asciidoctor.ast.Cell; +import org.asciidoctor.ast.Row; + +public class RowImpl implements Row { Review Comment: ```suggestion public final class RowImpl implements Row { ``` ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/TableImpl.java: ########## @@ -0,0 +1,120 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.ArrayList; +import java.util.List; +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.Column; +import org.asciidoctor.ast.ContentNode; +import org.asciidoctor.ast.Row; +import org.asciidoctor.ast.Table; + +public class TableImpl extends StructuralNodeImpl implements Table { Review Comment: ```suggestion public final class TableImpl extends StructuralNodeImpl implements Table { ``` ########## log4j-docgen/src/test/resources/expected/processor/JavadocExample.adoc: ########## @@ -0,0 +1,105 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// +Example of JavaDoc to AsciiDoc conversion + +We run the `javadoc` tool on this class to test conversion of JavaDoc comments to AsciiDoc. +This paragraph has two sentences. + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Vestibulum blandit dictum sem, ornare posuere lorem convallis sit amet. +Sed dui augue, faucibus ut nisi id, mollis euismod nibh. +Donec lobortis luctus viverra. +In orci ante, pretium et fringilla at, sagittis nec justo. +Cras finibus lorem vel volutpat interdum. +Sed laoreet libero eros, ac cursus nibh dapibus vitae. +Integer ante lorem, rhoncus at tortor vel, congue accumsan lorem. +In hac habitasse platea dictumst. +Nunc luctus ornare justo. +Etiam ut metus id tortor dignissim semper. +Nam turpis dui, aliquet nec enim et, faucibus accumsan dui. + +Aenean tincidunt elit id posuere mattis. +Fusce bibendum sapien sed risus ultricies, non molestie erat volutpat. +Donec nisi felis, egestas eu lobortis id, vulputate nec felis. +In at dui euismod, blandit nulla et, accumsan elit. +Proin id venenatis dui. +Suspendisse sit amet est ut neque tincidunt venenatis. +Donec bibendum quis velit fermentum porttitor. +Maecenas faucibus, eros sit amet maximus malesuada, turpis neque bibendum justo, eu vehicula justo metus a ipsum. +In at ullamcorper ipsum. +Quisque in vehicula erat. +Proin vitae suscipit dui, rutrum hendrerit augue. +Curabitur finibus feugiat elit. + +. Item with a nested ordered list. ++ +.. First nested item. +.. Second nested item. +. Item with a nested unordered list. ++ +* Unordered list item. +. Item with complex content ++ +Mauris suscipit velit nec ligula mattis, nec varius augue accumsan. +Curabitur a dolor dui. +Quisque congue facilisis est nec dignissim. +Pellentesque egestas eleifend faucibus. +Fusce imperdiet ligula a lectus fringilla varius. +Sed malesuada porta vulputate. +Sed vulputate purus nec nibh interdum convallis. +Cras faucibus, dolor tempus lacinia vehicula, elit risus luctus libero, sed molestie nisi lorem sit amet enim. +Integer vitae enim sagittis, malesuada lorem at, interdum tellus. +Suspendisse potenti. +Vestibulum ac nisi sit amet ex dictum suscipit. +Nulla varius augue a velit tincidunt feugiat. +Proin fringilla id leo ut dignissim. +Vivamus eu tellus eget orci suscipit viverra. +Donec sodales et arcu vel mollis. ++ +Praesent gravida auctor lectus quis interdum. +Etiam semper mauris quis neque bibendum molestie. +Maecenas a lacus nec risus pellentesque accumsan. +Suspendisse dictum dui eleifend nibh facilisis, non consequat neque elementum. +Donec scelerisque ultricies ipsum, pretium elementum ex pellentesque malesuada. +Mauris egestas massa vitae sapien lobortis convallis. +Donec feugiat, purus commodo consequat vehicula, dolor urna aliquam arcu, id rutrum quam tortor quis libero. +Sed varius justo eget congue lacinia. + +* Item of an unordered list. + +== First section + +[cols="1,1",options="headers"] +|=== + +| Key +| Value + +| A +| 1 + +| B +| 2 + +|=== + +=== Subsection + +[source] +---- + private static final Logger logger = LogManager.getLogger(); Review Comment: Can we remove the leading whitespace? ########## log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/internal/SectionImpl.java: ########## @@ -0,0 +1,108 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to you under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.logging.log4j.docgen.processor.internal; + +import java.util.ArrayList; +import java.util.List; +import org.apache.logging.log4j.util.StringBuilderFormattable; +import org.asciidoctor.ast.ContentNode; +import org.asciidoctor.ast.Document; +import org.asciidoctor.ast.Section; +import org.asciidoctor.ast.StructuralNode; + +public class SectionImpl extends StructuralNodeImpl implements Section { Review Comment: ```suggestion public final class SectionImpl extends StructuralNodeImpl implements Section { ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
