feat: Javadoc parser submodule #4748
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| --- | ||
| title: Javadoc parsing | ||
| tags: [javadoc, javadoc-parsing] | ||
| keywords: javadoc, javadoc-parsing, comments, spoon | ||
| --- | ||
|
|
||
| The spoon-javadoc submodule provides a parser for javadoc comments, producing a | ||
| structured syntax tree representing the comment. Each tag is parsed and | ||
| tokenized according to the rules in the javadoc specification. Additionally, | ||
| references in e.g. `@link` or `@see` tags are resolved to `CtReference`s, | ||
| allowing you to easily analyze them. | ||
|
|
||
| A visitor infrastructure is also provided, which eases analyzing comments or | ||
| converting them into your own format. | ||
|
|
||
| ### Installation | ||
|
|
||
| On a Unix-like system, the following set of commands should be sufficient for | ||
| getting spoon-javadoc up and running from scratch. | ||
|
|
||
| ``` | ||
| $ git clone https://github.com/INRIA/spoon.git | ||
| $ cd spoon/spoon-pom | ||
| $ mvn install | ||
| ``` | ||
|
|
||
| ### Basic usage | ||
|
|
||
| To get started you get the raw javadoc string (including `/**` and `*/`) and | ||
| pass it to a newly created `JavadocParser`. | ||
| You then call `parse` and get back a list of elements, corresponding to text, | ||
| inline tags or block tags. | ||
| Using a `JavadocVisitor` you can then visit each of them and drill down a bit. | ||
|
|
||
| In the following example, javadoc is parsed and then printed out again -- but | ||
| this time with some ANSI color highlighting applied. Note that references are | ||
| pretty-printed according to `CtReference#toString()`. | ||
|
|
||
| <details> | ||
|
|
||
| <summary>Expand me for the code </summary> | ||
|
|
||
| ```java | ||
| void example() { | ||
| String javadoc = "/**\n" + | ||
| " * Hello world, this is a description.\n" + | ||
| " * How are you doing? I am just fine :)\n" + | ||
| " * This is an inline link {@link String} and one with a {@link String label}\n" + | ||
| " * and a {@link String#CASE_INSENSITIVE_ORDER field} and {@link String#replace(char, char) with a space}.\n" + | ||
| " * {@link java.lang.annotation.Target @Target} chained to @Target.\n" + | ||
| " * <p>\n" + | ||
| " * We can also write <em>very HTML</em> {@code code}.\n" + | ||
| " * And an index: {@index \"Hello world\" With a phrase} or {@index without Without a phrase}.\n" + | ||
| " * {@snippet lang = java id = \"example me\" foo = 'bar':\n" + | ||
| " * public void HelloWorld(){ //@start region = \"foo\"\n" + | ||
| " * System.out.println(\"Hello World!\"); // @highlight substring=\"println\"\n" + | ||
| " * int a = 10; // @start foo=bar :\n" + | ||
| " * int a = 10; // @end\n" + | ||
| " * } // @end region=foo\n" + | ||
| " *}\n" + | ||
| " * <h2><a id=\"resolution\"></a>{@index \"Module Resolution\"}</h2>\n" + | ||
| " *\n" + | ||
| " * @param args some argument\n" + | ||
| " * @author a poor {@literal man}\n" + | ||
| " * hello world\n" + | ||
| " * @see String#contains(CharSequence) with a label\n" + | ||
| " * @see String#replace(char, char)\n" + | ||
| " */\n"; | ||
|
|
||
| List<JavadocElement> elements = new JavadocParser( | ||
| // Raw comment string including "/*" and "**/" | ||
| // You can get this using CtComment#getRawContent from a spoon element. | ||
| javadoc, | ||
| // The reference element so resolving of links works correctly. | ||
| // Javadoc comments can use "#foo" to refer to fields/methods | ||
| // in the current class. | ||
| new Launcher().getFactory().Type().OBJECT.getTypeDeclaration() | ||
| ).parse(); | ||
|
|
||
| for (JavadocElement element : elements) { | ||
| System.out.print(element.accept(new ExampleVisitor())); | ||
| } | ||
| } | ||
|
|
||
| private static class ExampleVisitor implements JavadocVisitor<String> { | ||
|
|
||
| @Override | ||
| public String defaultValue() { | ||
| throw new RuntimeException("Visit method not implemented"); | ||
| } | ||
|
|
||
| @Override | ||
| public String visitInlineTag(JavadocInlineTag tag) { | ||
| String result = "{@\033[36m" + tag.getTagType().getName() + "\033[0m"; | ||
| for (JavadocElement element : tag.getElements()) { | ||
| result += " " + element.accept(this); | ||
| } | ||
| result += "}"; | ||
| return result; | ||
| } | ||
|
|
||
| @Override | ||
| public String visitBlockTag(JavadocBlockTag tag) { | ||
| String result = "@\033[36m" + tag.getTagType().getName() + "\033[0m "; | ||
| for (JavadocElement element : tag.getElements()) { | ||
| result += element.accept(this); | ||
| } | ||
| result += "\n"; | ||
| return result; | ||
| } | ||
|
|
||
| @Override | ||
| public String visitText(JavadocText text) { | ||
| return text.getText(); | ||
| } | ||
|
|
||
| @Override | ||
| public String visitReference(JavadocReference reference) { | ||
| return "\033[31m" + reference.getReference() + "\033[0m"; | ||
| } | ||
|
|
||
| @Override | ||
| public String visitSnippet(JavadocSnippetTag snippet) { | ||
| String result = "{@\033[36m" + snippet.getTagType().getName() + "\033[0m "; | ||
| result += snippet.getAttributes() | ||
| .entrySet() | ||
| .stream() | ||
| .sorted(Map.Entry.comparingByKey()) | ||
| .map(entry -> entry.getKey() + "='" + entry.getValue() + "'") | ||
| .collect(Collectors.joining(" ")); | ||
|
|
||
| result += " : "; | ||
| for (JavadocElement element : snippet.getElements()) { | ||
| result += element.accept(this); | ||
| } | ||
|
|
||
| result += "}\n"; | ||
| return result; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
| <br> | ||
| This will print a version with a bit more colours: | ||
| ![ANSI colored javadoc]({{ "/images/spoon_javadoc_ansi_print.png" | prepend: site.baseurl }}) | ||
|
|
||
| ### Snippets | ||
| Spoon-javadoc provides the `JavadocSnippetBody` class to help parse javadoc | ||
| snippets: | ||
| ```java | ||
| JavadocSnippetBody body = JavadocSnippetBody.fromString( | ||
| "class Foo { // @start region=\"foo\"\n" + | ||
| " int p0 = 0; // @start region=\"bar\"\n" + | ||
| " int p1 = 1;\n" + | ||
| " int p2 = 2; // @end\n" + | ||
| " int p3 = 3; // @end\n" + | ||
| "}\n" | ||
| ); | ||
| body.getLines(); // returns all lines of the original snippet | ||
| body.getRegions(); // returns all start/highlight/link regions | ||
| body.getActiveRegionsAtLine(0); // returns all regions active in the given line | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <project xmlns="http://maven.apache.org/POM/4.0.0" | ||
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> | ||
| <parent> | ||
| <artifactId>spoon-pom</artifactId> | ||
| <groupId>fr.inria.gforge.spoon</groupId> | ||
| <version>1.0</version> | ||
| <relativePath>../spoon-pom</relativePath> | ||
| </parent> | ||
| <modelVersion>4.0.0</modelVersion> | ||
|
|
||
| <artifactId>spoon-javadoc</artifactId> | ||
| <packaging>jar</packaging> | ||
| <version>10.4.0-SNAPSHOT</version> | ||
| <name>Spoon Javadoc</name> | ||
| <description>A javadoc parser for the java source code analysis tool spoon.</description> | ||
|
|
||
| <build> | ||
| <plugins> | ||
| <plugin> | ||
| <groupId>org.jacoco</groupId> | ||
| <artifactId>jacoco-maven-plugin</artifactId> | ||
| <executions> | ||
| <execution> | ||
| <goals> | ||
| <goal>prepare-agent</goal> | ||
| </goals> | ||
| </execution> | ||
| <execution> | ||
| <id>report</id> | ||
| <phase>prepare-package</phase> | ||
| <goals> | ||
| <goal>report</goal> | ||
| </goals> | ||
| </execution> | ||
| <execution> | ||
| <id>check-coverage</id> | ||
| <goals> | ||
| <goal>check</goal> | ||
| </goals> | ||
| <configuration> | ||
| <rules> | ||
| <rule implementation="org.jacoco.maven.RuleConfiguration"> | ||
| <element>CLASS</element> | ||
| <limits> | ||
| <limit implementation="org.jacoco.report.check.Limit"> | ||
| <counter>LINE</counter> | ||
| <value>COVEREDRATIO</value> | ||
| <minimum>0.1</minimum> | ||
| </limit> | ||
| </limits> | ||
| </rule> | ||
| </rules> | ||
| </configuration> | ||
| </execution> | ||
| </executions> | ||
| </plugin> | ||
| </plugins> | ||
| </build> | ||
|
|
||
| <dependencies> | ||
| <dependency> | ||
| <groupId>fr.inria.gforge.spoon</groupId> | ||
| <artifactId>spoon-core</artifactId> | ||
| <version>${version}</version> | ||
| <scope>provided</scope> | ||
| </dependency> | ||
|
|
||
| <dependency> | ||
| <groupId>org.assertj</groupId> | ||
| <artifactId>assertj-core</artifactId> | ||
| <version>3.24.2</version> | ||
| <scope>test</scope> | ||
| </dependency> | ||
|
Comment on lines
+70
to
+75
There was a problem hiding this comment. Maybe it is time to simply add this to the parent? There was a problem hiding this comment. You mean in the dependency management section? There was a problem hiding this comment. No the complete test dependency |
||
| </dependencies> | ||
|
|
||
| </project> | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| /* | ||
| * SPDX-License-Identifier: (MIT OR CECILL-C) | ||
| * | ||
| * Copyright (C) 2006-2019 INRIA and contributors | ||
| * | ||
| * Spoon is available either under the terms of the MIT License (see LICENSE-MIT.txt) of the Cecill-C License (see LICENSE-CECILL-C.txt). You as the user are entitled to choose the terms under which to adopt Spoon. | ||
| */ | ||
| package spoon.javadoc.api; | ||
|
|
||
| /** | ||
| * The category (block or inline) a javadoc tag belongs to. A tag might be able to be used as | ||
| * <em>both</em> (e.g. {@code @return}. | ||
| */ | ||
| public enum JavadocTagCategory { | ||
| INLINE, | ||
| BLOCK, | ||
MartinWitt marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a reason to have this multiline?