pax_global_header 0000666 0000000 0000000 00000000064 14050521027 0014506 g ustar 00root root 0000000 0000000 52 comment=54d55175b6500b4742ea3cf142263b2ef955da13
vertx-docgen-0.9.4/ 0000775 0000000 0000000 00000000000 14050521027 0014125 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/.editorconfig 0000664 0000000 0000000 00000000223 14050521027 0016577 0 ustar 00root root 0000000 0000000 root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
trim_trailing_whitespace = true
end_of_line = lf
insert_final_newline = true
vertx-docgen-0.9.4/.gitignore 0000664 0000000 0000000 00000000326 14050521027 0016116 0 ustar 00root root 0000000 0000000 pom.xml.versionsBackup
.DS_Store
.gradle
.idea
*.iml
*.ipr
*.iws
.classpath
.project
.settings
.yardoc
.yardopts
bin
build
target
out
test-output
Scratch.java
ScratchTest.java
test-results
test-tmp
*.class
src/gen
vertx-docgen-0.9.4/.travis.deploy.artifacts.sh 0000664 0000000 0000000 00000000515 14050521027 0021322 0 ustar 00root root 0000000 0000000 PROJECT_VERSION=$(mvn org.apache.maven.plugins:maven-help-plugin:evaluate -Dexpression=project.version -B | grep -v '\[')
if [[ "$PROJECT_VERSION" =~ .*SNAPSHOT ]] && [[ "${TRAVIS_BRANCH}" =~ ^master$|^[0-9]+\.[0-9]+$ ]] && [[ "${TRAVIS_PULL_REQUEST}" = "false" ]];
then
mvn deploy -s .travis.maven.settings.xml -DskipTests -B;
fi
vertx-docgen-0.9.4/.travis.maven.settings.xml 0000664 0000000 0000000 00000001020 14050521027 0021172 0 ustar 00root root 0000000 0000000 falsesonatype-nexus-snapshots${env.SONATYPE_NEXUS_USERNAME}${env.SONATYPE_NEXUS_PASSWORD}
vertx-docgen-0.9.4/.travis.yml 0000664 0000000 0000000 00000001352 14050521027 0016237 0 ustar 00root root 0000000 0000000 language: java
branches:
only:
- master
- /^\d+\.\d+$/
cache:
directories:
- $HOME/.m2
before_cache:
- rm -rf $HOME/.m2/repository/io/vertx/
jobs:
include:
- stage: test
name: "OpenJDK 8"
jdk: openjdk8
script: mvn -q clean verify -B
- stage: deploy
name: "Deploy to Sonatype's snapshots repository"
if: type != pull_request AND env(SONATYPE_NEXUS_USERNAME) IS present
script: bash .travis.deploy.artifacts.sh
notifications:
email:
recipients:
- secure: "V2q/8MNZl3n735Yq2ELXXge8Dhhvk2Js3XauNenWZtqLnKoonANcl8RZir5tTnL67+P6GSqxwb4L9DyipuyZXTgoyTPDi/vTD2Qf2BJFdN8nsYJrdf3ABEbLHqU8BoKogt9JD+AWYCsPGeAnXc2GvDmewHhgB0S6UUa5BeEbWxw="
on_success: always
on_failure: always
vertx-docgen-0.9.4/LICENSE.txt 0000664 0000000 0000000 00000026135 14050521027 0015757 0 ustar 00root root 0000000 0000000 Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "{}"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright {yyyy} {name of copyright owner}
Licensed 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.
vertx-docgen-0.9.4/README.md 0000664 0000000 0000000 00000012547 14050521027 0015415 0 ustar 00root root 0000000 0000000 # Docgen
[](https://travis-ci.org/vert-x3/vertx-docgen)
## Description
Create an Asciidoc document from package Javadoc. It comes as an annotation processor that process the various
package Javadoc and create a single Asciidoc file during the compilation phase.
## Motivation
- The documentation can reference the underlying API doc (Javadoc, Scaladoc, JSdoc, etc…) : when the Asciidoc
content is created the `{@link}` are transformed to a link to the API doc
- The documentation always point to an existing API, i.e the {@link} references validity are checked
and make the compilation fails
- Refactoring friendly, when you rename a method the corresponding {@link} are updated, allowing you
easily spot the affected doc (using git diff or something)
## Features
### Document declaration
`@Document` annotations are processed, each annotated package creates a corresponding asciidoc document. The
annotation can specify an optional `fileName` member otherwise the document file name will be generated using the
annotated element.
File documents can also be processed with the `docgen.source` processor option.
### Document modulalization
The `{@link }` Javadoc tag includes or link to the target doc when the target is a package. This can be used to make your
documentation modular and split the various chapters of the document accross the API packages.
When the package is annotated with `@Document` the link renders to a relative file url, otherwise its content
will be literaly included in the document.
### Source inclusion
The `{@link }` Javadoc tag includes the referenced elements when this element is annotated with a `io.vertx.docgen.Source`
annotation (otherwise it will just create a link). The `@Source` annotation can annotate a single method, a class
or a package.
By default the source code is translated to the output language. This feature can be disabled with `@Source
(translate=false)`. When including source code, the _closest_ (class, package, parent package...) `@Source` annotation
is looked up and the value of the `translate` attribute is used.
When `translate` is set to `false`, it supports the inclusion of Java file (entire file) in the documentation with
the following syntax:
```
[source, java]
----
{@link org.acme.MyClass}
----
```
### Lang token
The `$lang` token is replaced by the processed language in:
- `docgen.output`
- processed text (@Source is excluded)
The `\$lang` escapes to `$lang`.
### Language-based content
You can decided that some content is only applicable for a set of languages. This is doable using:
```
[language, java]
----
This is only for java
----
```
or
```
[language, ruby, groovy]
----
This is only for ruby and groovy.
----
```
If the block is only on one line the following syntax is accepted:
```
[language, ruby]
This is only for ruby
```
If the block contains a "sub-block" such as code, the `----` must be prepended by a `\`:
```
[language, java]
----
[source]
\----
System.out.println("Hello");
\----
----
```
### Referencing program elements
The `{@link }` Javadoc tag creates a link to the Javadoc of a program element when the target is
a type, a field or a method.
## Configuration
The annotation processor can be configured via annotation processing options:
- `docgen.output` : path of the file output dir, the path may contain the token `$lang` that will be subsituted by
the current language being generated (the `docgen.json` name field)
- `docgen.extension` : the file extension to use when file names are generated, defaults to `.adoc`
## Example
See the nested [test_proj](https://github.com/vert-x3/vertx-docgen/tree/master/test-proj) project for Maven and Gradle examples.
Given the files:
```
/**
* = The great project
*
* include::{@link test.proj.foofeature}[]
*
*/
@io.vertx.docgen.Document(fileName = "index.adoc")
package test.proj;
```
```
/**
* == The foo feature.
*
* The {@link test.proj.foofeature.FooApi api class}
* The {@link test.proj.foofeature.FooApi#myMethod api method}
* The {@link test.proj.foofeature.FooApi#myField api field}
*
* * item1
* * item 2
* * item 3
*
* Some code:
*
* [source,java]
* ----
* {@link test.proj.foofeature.Examples#fooExample}
* ----
* <1> get a Foo
* <2> call {@link test.proj.foofeature.FooApi#myMethod api method}
*
* === A sub section
*
* {@link test.proj.foofeature.subsection}
*/
@io.vertx.docgen.Document
package test.proj.foofeature;
```
```
/**
* A literaly included section
*/
package test.proj.foofeature.subsection;
```
Generate the following Asciidoc files:
```
= The great project
include::test.proj.foofeature.adoc[]
```
_test.proj.adoc_
```
== The foo feature.
The link:apidocs/test/proj/foofeature/FooApi.html[`api class`]
The link:apidocs/test/proj/foofeature/FooApi.html#myMethod-java.lang.String-int-java.util.List-java.util.Set-[`api method`]
The link:apidocs/test/proj/foofeature/FooApi.html#myField[`api field`]
* item1
* item 2
* item 3
Some code:
[source,java]
----
FooApi foo = getFoo(); // <1>
List list = new ArrayList<>();
Set set = new HashSet<>();
foo.myMethod("whatever", 0, list, set); // <2>
----
<1> get a Foo
<2> call link:apidocs/test/proj/foofeature/FooApi.html#myMethod-java.lang.String-int-java.util.List-java.util.Set-[`api method`]
=== A sub section
A literaly included section
```
_test.proj.foofeature.adoc_
vertx-docgen-0.9.4/pom.xml 0000664 0000000 0000000 00000004006 14050521027 0015442 0 ustar 00root root 0000000 0000000
io.vertxvertx-parent194.0.0vertx-docgen0.9.4scm:git:git@github.com:vert-x3/vertx-docgen.gitscm:git:git@github.com:vert-x3/vertx-docgen.gitgit@github.com:vert-x3/vertx-docgen.git${java.home}/../lib/tools.jarcom.suntools1.8system${tools.jar}truejunitjunit4.12testmaven-compiler-plugindefault-testCompileio/vertx/test/**org.apache.maven.pluginsmaven-surefire-plugin
vertx-docgen-0.9.4/src/ 0000775 0000000 0000000 00000000000 14050521027 0014714 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/ 0000775 0000000 0000000 00000000000 14050521027 0015640 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/java/ 0000775 0000000 0000000 00000000000 14050521027 0016561 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/java/io/ 0000775 0000000 0000000 00000000000 14050521027 0017170 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/java/io/vertx/ 0000775 0000000 0000000 00000000000 14050521027 0020340 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/ 0000775 0000000 0000000 00000000000 14050521027 0021577 5 ustar 00root root 0000000 0000000 vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/BaseProcessor.java 0000664 0000000 0000000 00000061546 14050521027 0025230 0 ustar 00root root 0000000 0000000 package io.vertx.docgen;
import com.sun.source.doctree.*;
import com.sun.source.doctree.ErroneousTree;
import com.sun.source.doctree.LiteralTree;
import com.sun.source.util.DocTreeScanner;
import com.sun.source.util.DocTrees;
import com.sun.source.util.TreePath;
import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import javax.tools.Diagnostic;
import javax.tools.JavaFileObject;
import java.io.*;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.*;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* @author Julien Viet
*/
public abstract class BaseProcessor extends AbstractProcessor {
private static final String DOCGEN_OUTPUT = "docgen.output", DOCGEN_EXTENSION = "docgen.extension",
DOCGEN_SOURCE = "docgen.source", DOCGEN_SYNTAX = "docgen.syntax";
protected DocTrees docTrees;
protected Helper helper;
protected List sources;
protected Set postProcessors = new LinkedHashSet<>();
protected Map resolutions = new HashMap<>();
protected Syntax syntax;
Map failures = new HashMap<>();
@Override
public SourceVersion getSupportedSourceVersion() {
return SourceVersion.RELEASE_8;
}
@Override
public Set getSupportedOptions() {
return new HashSet<>(Arrays.asList(DOCGEN_OUTPUT, DOCGEN_EXTENSION, DOCGEN_SOURCE));
}
@Override
public Set getSupportedAnnotationTypes() {
return Collections.singleton("*");
}
public synchronized BaseProcessor registerPostProcessor(PostProcessor postProcessor) {
if (getPostProcessor(postProcessor.getName()) != null) {
throw new IllegalArgumentException("Post-processor with name '" + postProcessor.getName() + "' is already " +
"registered.");
}
postProcessors.add(postProcessor);
return this;
}
public synchronized PostProcessor getPostProcessor(String name) {
for (PostProcessor pp : postProcessors) {
if (pp.getName().equalsIgnoreCase(name)) {
return pp;
}
}
return null;
}
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
String sourceOpt = processingEnv.getOptions().get(DOCGEN_SOURCE);
if (sourceOpt != null) {
sources = new ArrayList<>(Arrays.asList(sourceOpt.split("\\s*,\\s*")));
}
docTrees = DocTrees.instance(processingEnv);
helper = new Helper(processingEnv);
String syntaxOpt = processingEnv.getOptions().get(DOCGEN_SYNTAX);
this.syntax = "markdown".equals(syntaxOpt) ? Syntax.MARKDOWN : Syntax.ASCIIDOC;
registerPostProcessor(new LanguageFilterPostProcessor());
}
private String render(List trees) {
StringBuilder buffer = new StringBuilder();
DocTreeVisitor visitor = new DocTreeScanner() {
@Override
public Void visitText(TextTree node, Void aVoid) {
buffer.append(node.getBody());
return super.visitText(node, aVoid);
}
};
trees.forEach(tree -> tree.accept(visitor, null));
return buffer.toString();
}
private final Map> state = new HashMap<>();
@Override
public boolean process(Set annotations, RoundEnvironment roundEnv) {
StackTraceElement[] trace = Thread.currentThread().getStackTrace();
for (StackTraceElement elt : trace) {
if (elt.getClassName().startsWith("org.jetbrains")) {
return true;
}
}
if (failures.isEmpty()) {
try {
if (!roundEnv.processingOver()) {
roundEnv.getElementsAnnotatedWith(Document.class).forEach(elt -> {
try {
PackageDoc doc = new PackageDoc((PackageElement) elt);
state.put(doc, handleGen(doc));
} catch (DocGenException e) {
if (e.element == null) {
e.element = elt;
}
throw e;
}
});
if (sources != null && sources.size() > 0) {
for (String source : sources) {
// Handle wildcards
List files = new ArrayList<>();
File f = new File(source);
if (!f.exists()) {
if (f.getName().contains("*")) {
StringBuilder sb = new StringBuilder();
for (char c : f.getName().toCharArray()) {
if (c == '*') {
sb.append(".*");
} else {
sb.append(Matcher.quoteReplacement(Character.toString(c)));
}
}
Pattern p = Pattern.compile(sb.toString());
File parentFile = f.getParentFile();
File[] children = parentFile.listFiles();
if (children != null) {
for (File child : children) {
if (p.matcher(child.getName()).matches()) {
files.add(child);
}
}
}
} else {
throw new FileNotFoundException("Cannot process document " + source);
}
} else {
files.add(f);
}
for (File file : files) {
if (file.isFile()) {
FileDoc fileDoc = new FileDoc(file, file.getName());
Map m = handleGen(fileDoc);
state.put(fileDoc, m);
} else if (file.isDirectory()) {
Files.walk(file.toPath())
.map(Path::toFile)
.filter(File::isFile).forEach(docFile -> {
String relativePath = file.toPath().relativize(docFile.toPath()).toString();
FileDoc fileDoc = new FileDoc(docFile, relativePath);
Map m = handleGen(fileDoc);
state.put(fileDoc, m);
});
} else {
throw new IOException("Document " + file.getAbsolutePath() + " is not a file nor a dir");
}
}
}
sources.clear();
}
Set processed = new HashSet<>();
while (true) {
Optional opt = resolutions
.values()
.stream()
.filter(res -> res.elt == null && !processed.contains(res.signature))
.findFirst();
if (opt.isPresent()) {
ElementResolution res = opt.get();
processed.add(res.signature);
res.tryResolve();
} else {
break;
}
}
} else {
state.forEach((doc, m) -> {
m.forEach((gen, w) -> {
String content = postProcess(gen.getName(), w.render());
write(gen, doc, content);
});
});
}
} catch(Exception e) {
Element reportedElt = (e instanceof DocGenException) ? ((DocGenException) e).element : null;
String msg = e.getMessage();
if (msg == null) {
msg = e.toString();
}
e.printStackTrace();
if (reportedElt != null) {
processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, msg, reportedElt);
if (reportedElt instanceof PackageElement) {
failures.put(((PackageElement) reportedElt).getQualifiedName().toString(), msg);
} else {
throw new UnsupportedOperationException("not implemented");
}
} else {
processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, msg);
}
}
}
return false;
}
protected abstract Iterable generators();
private Map handleGen(Doc doc) {
Map map = new HashMap<>();
for (DocGenerator generator : generators()) {
generator.init(processingEnv);
DocWriter writer = new DocWriter();
doc.process(generator, writer);
map.put(generator, writer);
}
return map;
}
/**
* @return the extension obtained from processor option {@literal docgen.extension} defaults to {@literal .adoc}
* when absent.
*/
protected String getExtension() {
String extension = processingEnv.getOptions().get(DOCGEN_EXTENSION);
if (extension != null) {
return extension;
}
return ".adoc";
}
protected String resolveLinkToPackageDoc(PackageElement elt) {
Document annotation = elt.getAnnotation(Document.class);
String fileName = annotation.fileName();
if (fileName.isEmpty()) {
return elt.toString() + getExtension();
} else {
return fileName;
}
}
private URL getURL(JavaFileObject fileObject) {
try {
return fileObject.toUri().toURL();
} catch (Exception e) {
return null;
}
}
/**
* Resolve a label for the specified element, this is used when a link to a program element
* does not specify an explicit label.
*
* Subclasses can override it to implement a particular behavior for elements.
*
* @param elt the elt to resolve a label for
* @return the label
*/
private String resolveLabel(DocGenerator generator, Element elt) {
String label = elt.getSimpleName().toString();
if (elt.getModifiers().contains(Modifier.STATIC) &&
(elt.getKind() == ElementKind.METHOD || elt.getKind() == ElementKind.FIELD)) {
label = elt.getEnclosingElement().getSimpleName() + "." + label;
}
if (elt.getKind() == ElementKind.ANNOTATION_TYPE) {
label = "@" +label;
}
return generator.resolveLabel(elt, label);
}
private final LinkedList stack = new LinkedList<>();
abstract class Doc {
abstract String id();
abstract String resolveRelativeFileName(DocGenerator generator);
protected final void process(DocGenerator generator, DocWriter writer) {
if (this instanceof PackageDoc) {
PackageElement pkgElt = ((PackageDoc) this).elt;
for (PackageElement stackElt : stack) {
if (pkgElt.getQualifiedName().equals(stackElt.getQualifiedName())) {
throw new DocGenException(stack.peekLast(), "Circular include");
}
}
stack.addLast(pkgElt);
String pkgSource = helper.readSource(pkgElt);
TreePath pkgPath = docTrees.getPath(pkgElt);
DocCommentTree docTree = docTrees.getDocCommentTree(pkgPath);
DocTreeVisitor visitor = new DocTreeScanner() {
private void copyContent(DocTree node) {
int from = (int) docTrees.getSourcePositions().getStartPosition(pkgPath.getCompilationUnit(), docTree, node);
int to = (int) docTrees.getSourcePositions().getEndPosition(pkgPath.getCompilationUnit(), docTree, node);
writer.append(pkgSource, from, to);
}
@Override
public Void visitUnknownBlockTag(UnknownBlockTagTree node, Void v) {
writer.append("@").append(node.getTagName()).append(" ");
return super.visitUnknownBlockTag(node, v);
}
@Override
public Void visitDocComment(DocCommentTree node, Void v) {
v = scan(node.getFirstSentence(), v);
List body = node.getBody();
if (body.size() > 0) {
writer.append("\n\n");
writer.resetParagraph();
v = scan(body, v);
}
List blockTags = node.getBlockTags();
if (blockTags.size() > 0) {
writer.append("\n");
v = scan(blockTags, v);
}
return v;
}
@Override
public Void visitErroneous(ErroneousTree node, Void v) {
return visitText(node, v);
}
@Override
public Void visitText(TextTree node, Void v) {
String body = node.getBody();
helper.filterLang(body, generator.getName(), writer);
return super.visitText(node, v);
}
/**
* Handles both literal and code. We generate the asciidoc output using {@literal `}.
*/
@Override
public Void visitLiteral(LiteralTree node, Void aVoid) {
writer.append("`").append(node.getBody().getBody()).append("`");
return super.visitLiteral(node, aVoid);
}
@Override
public Void visitEntity(EntityTree node, Void aVoid) {
writer.append(EntityUtils.unescapeEntity(node.getName().toString()));
return super.visitEntity(node, aVoid);
}
@Override
public Void visitStartElement(StartElementTree node, Void v) {
copyContent(node);
return v;
}
@Override
public Void visitEndElement(EndElementTree node, Void v) {
writer.write("');
return v;
}
@Override
public Void visitLink(LinkTree node, Void v) {
String signature = node.getReference().getSignature();
String label = render(node.getLabel()).trim();
BaseProcessor.this.visitLink(pkgElt, label, signature, generator, writer);
return v;
}
};
docTree.accept(visitor, null);
stack.removeLast();
} else {
FileDoc fileDoc = (FileDoc) this;
try {
String content = new String(Files.readAllBytes(fileDoc.file.toPath()), StandardCharsets.UTF_8);
StringBuilder intermediate = new StringBuilder(content.length());
helper.filterLang(content, generator.getName(), intermediate);
content = intermediate.toString();
Matcher linkMatcher = LINK_PATTERN.matcher(content);
int prev = 0;
while (linkMatcher.find()) {
writer.write(content, prev, linkMatcher.start() - prev);
String value = linkMatcher.group(1).trim();
Matcher methodLinkMatcher = METHOD_LINK_PATTERN.matcher(value);
if (methodLinkMatcher.find()) {
String signature = value.substring(0, methodLinkMatcher.end());
String label = value.substring(methodLinkMatcher.end()).trim();
writer.exec(() -> {
BaseProcessor.this.visitLink(null, label, signature, generator, writer);
});
}
prev = linkMatcher.end();
}
writer.append(content, prev, content.length());
} catch (IOException e) {
throw new DocGenException(e.getMessage());
}
}
}
}
class PackageDoc extends Doc {
final PackageElement elt;
PackageDoc(PackageElement elt) {
this.elt = elt;
}
@Override
public String id() {
return elt.getQualifiedName().toString();
}
/**
* Return the relative file name of a document.
*
* @param generator the doc generator
* @return the relative file name
*/
public String resolveRelativeFileName(DocGenerator generator) {
Document doc = elt.getAnnotation(Document.class);
String relativeName = doc.fileName();
if (relativeName.isEmpty()) {
relativeName = elt.getQualifiedName() + getExtension();
}
return generator.resolveRelativeFileName(elt, relativeName);
}
}
class FileDoc extends Doc {
final File file;
final String relativePath;
FileDoc(File file, String relativePath) {
this.file = file;
this.relativePath = relativePath;
}
@Override
public String id() {
return relativePath;
}
@Override
public String resolveRelativeFileName(DocGenerator generator) {
return relativePath;
}
}
private static final Pattern LINK_PATTERN = Pattern.compile("\\{@link\\s([^}]+)\\}");
private static final Pattern METHOD_LINK_PATTERN = Pattern.compile(
"^([$_\\w]+\\.)*[$_\\w]+" +
"(?:" +
"#[$_\\w]+" +
"(?:(?:\\([^)]*)\\)|$|(?= ))" +
")?");
private void visitLink(PackageElement pkgElt, String label, String signature, DocGenerator generator, DocWriter writer) {
ElementResolution res = resolutions.get(signature);
if (res == null) {
res = new ElementResolution(signature);
resolutions.put(signature, res);
}
LinkProcessing fut = new LinkProcessing(generator, label);
res.add(fut);
writer.write(() -> {
DocWriter ww = fut.writer;
if (ww == null) {
throw new DocGenException(pkgElt, "Could not resolve " + signature);
}
return ww;
});
}
/**
* The resolution of an element.
*/
class ElementResolution {
final String signature;
private Element elt;
private List handlers = new ArrayList<>();
public ElementResolution(String signature) {
this.signature = signature;
}
boolean tryResolve() {
if (elt == null) {
doResolve();
}
return elt != null;
}
public boolean equals(Object o) {
if (o instanceof ElementResolution) {
ElementResolution that = (ElementResolution) o;
return signature.equals(that.signature);
} else {
return false;
}
}
@Override
public int hashCode() {
return signature.hashCode();
}
private void doResolve() {
elt = helper.resolveLink(signature);
if (elt != null) {
for (LinkProcessing fut : handlers) {
fut.handle(elt);
}
handlers.clear();
}
}
private void add(LinkProcessing fut) {
if (elt != null) {
fut.handle(elt);
} else {
handlers.add(fut);
}
}
}
class LinkProcessing {
final DocGenerator generator;
final String label;
private DocWriter writer;
public LinkProcessing(DocGenerator generator, String label) {
this.generator = generator;
this.label = label;
}
void handle(Element elt) {
writer = new DocWriter();
if (elt instanceof PackageElement) {
PackageElement includedElt = (PackageElement) elt;
if (includedElt.getAnnotation(Document.class) == null) {
new PackageDoc(includedElt).process(generator, writer);
} else {
String link = resolveLinkToPackageDoc((PackageElement) elt);
writer.append(link);
}
} else {
if (helper.isExample(elt)) {
String source = helper.readSource(elt);
switch (elt.getKind()) {
case CONSTRUCTOR:
case METHOD:
// Check whether or not the fragment must be translated
String fragment;
if (helper.hasToBeTranslated(elt)) {
// Invoke the custom renderer, this may should the translation to the expected language.
fragment = generator.renderSource((ExecutableElement) elt, source);
} else {
// Do not call the custom rendering process, just use the default / java one.
JavaDocGenerator javaGen = new JavaDocGenerator();
javaGen.init(processingEnv);
fragment = javaGen.renderSource((ExecutableElement) elt, source);
}
if (fragment != null) {
writer.literalMode();
writer.append(fragment);
writer.commentMode();
}
return;
case CLASS:
case INTERFACE:
case ENUM:
case ANNOTATION_TYPE:
TypeElement typeElt = (TypeElement) elt;
JavaDocGenerator javaGen = new JavaDocGenerator();
javaGen.init(processingEnv);
fragment = javaGen.renderSource(typeElt, source);
if (fragment != null) {
writer.literalMode();
writer.append(fragment);
writer.commentMode();
}
return;
default:
throw new UnsupportedOperationException("unsupported element: " + elt.getKind());
}
}
String link;
switch (elt.getKind()) {
case CLASS:
case INTERFACE:
case ANNOTATION_TYPE:
case ENUM: {
TypeElement typeElt = (TypeElement) elt;
link = generator.resolveTypeLink(typeElt);
break;
}
case METHOD: {
ExecutableElement methodElt = (ExecutableElement) elt;
TypeElement typeElt = (TypeElement) methodElt.getEnclosingElement();
link = generator.resolveMethodLink(methodElt);
break;
}
case CONSTRUCTOR: {
ExecutableElement constructorElt = (ExecutableElement) elt;
TypeElement typeElt = (TypeElement) constructorElt.getEnclosingElement();
link = generator.resolveConstructorLink(constructorElt);
break;
}
case FIELD:
case ENUM_CONSTANT: {
VariableElement variableElt = (VariableElement) elt;
TypeElement typeElt = (TypeElement) variableElt.getEnclosingElement();
link = generator.resolveFieldLink(variableElt);
break;
}
default:
throw new UnsupportedOperationException("Not yet implemented " + elt + " with kind " + elt.getKind());
}
String s;
if (label.length() == 0) {
s = resolveLabel(generator, elt);
} else {
s = label;
}
if (link != null) {
syntax.writeLink(link, s, writer);
} else {
writer.append("`").append(s).append("`");
}
}
}
}
protected String postProcess(String name, String content) {
String processed = applyVariableSubstitution(content);
processed = applyPostProcessors(name, processed);
return processed;
}
protected void write(DocGenerator generator, Doc doc, String content) {
String outputOpt = processingEnv.getOptions().get(DOCGEN_OUTPUT);
if (outputOpt != null) {
outputOpt = outputOpt.replace("$lang", generator.getName());
String relativeName = doc.resolveRelativeFileName(generator);
try {
File dir = new File(outputOpt);
for (int i = relativeName.indexOf('/'); i != -1; i = relativeName.indexOf('/', i + 1)) {
dir = new File(dir, relativeName.substring(0, i));
relativeName = relativeName.substring(i + 1);
}
File file = new File(dir, relativeName);
ensureDir(file.getParentFile());
try (FileWriter writer = new FileWriter(file)) {
writer.write(content);
}
} catch (IOException e) {
e.printStackTrace();
}
}
}
/**
* Apply post-processors.
*
* @param content the (asciidoc) content
* @return the content after post-processing.
*/
protected String applyPostProcessors(String name2, String content) {
final List lines = Arrays.asList(content.split("\r?\n"));
StringBuilder processed = new StringBuilder();
Iterator iterator = lines.iterator();
while (iterator.hasNext()) {
String line = iterator.next();
String trimmedLine = line.trim();
if (!PostProcessor.isBlockDeclaration(trimmedLine)) {
processed.append(line);
if (iterator.hasNext()) {
processed.append("\n");
}
} else {
String name = PostProcessor.getProcessorName(trimmedLine);
String[] attributes = PostProcessor.getProcessorAttributes(trimmedLine);
PostProcessor postProcessor = getPostProcessor(name);
if (postProcessor == null) {
processed.append(line);
if (iterator.hasNext()) {
processed.append("\n");
}
} else {
// Extract content.
String block = PostProcessor.getBlockContent(iterator);
processed.append(postProcessor.process(name2, block, attributes));
if (iterator.hasNext()) {
processed.append("\n");
}
}
}
}
return processed.toString();
}
private void ensureDir(File dir) {
if (dir.exists()) {
if (!dir.isDirectory()) {
throw new DocGenException("File " + dir.getAbsolutePath() + " is not a dir");
}
} else if (!dir.mkdirs()) {
throw new DocGenException("could not create dir " + dir.getAbsolutePath());
}
}
/**
* Replace `@{var} by the variable value passed to the annotation processor.
*
* @param content the content
* @return the content with variable values
*/
public String applyVariableSubstitution(String content) {
for (Map.Entry entry : processingEnv.getOptions().entrySet()) {
content = content.replace("${" + entry.getKey() + "}", entry.getValue());
}
return content;
}
}
vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/DocGenException.java 0000664 0000000 0000000 00000000601 14050521027 0025455 0 ustar 00root root 0000000 0000000 package io.vertx.docgen;
import javax.lang.model.element.Element;
/**
* @author Julien Viet
*/
public class DocGenException extends RuntimeException {
Element element;
public DocGenException(Element element, String msg) {
super(msg);
this.element = element;
}
public DocGenException(String msg) {
super(msg);
}
}
vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/DocGenProcessor.java 0000664 0000000 0000000 00000002271 14050521027 0025503 0 ustar 00root root 0000000 0000000 package io.vertx.docgen;
import javax.annotation.processing.ProcessingEnvironment;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import java.util.ServiceLoader;
/**
* A doc gen processor that runs multiple generators at once.
*
* @author Julien Viet
*/
public class DocGenProcessor extends BaseProcessor {
private List generators;
public DocGenProcessor() {
}
public DocGenProcessor(DocGenerator... generators) {
this.generators = Arrays.asList(generators.clone());
}
@Override
public synchronized void init(ProcessingEnvironment processingEnv) {
super.init(processingEnv);
// Service loader generators
if (generators == null) {
generators = new ArrayList<>();
Iterator it = ServiceLoader.load(DocGenerator.class, DocGenProcessor.class.getClassLoader()).iterator();
while (it.hasNext()) {
try {
generators.add(it.next());
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
@Override
protected Iterable generators() {
return generators;
}
}
vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/DocGenerator.java 0000664 0000000 0000000 00000004550 14050521027 0025022 0 ustar 00root root 0000000 0000000 package io.vertx.docgen;
import javax.annotation.processing.ProcessingEnvironment;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
/**
* A doc generator plugin.
*
* @author Julien Viet
*/
public interface DocGenerator {
/**
* Init the generator.
*
* @param env the processor environment
*/
void init(ProcessingEnvironment env);
/**
* @return the generator name
*/
String getName();
/**
* Resolve the relative file name of a document, the default implementation returns the {@literal relativeFileName}
* parameter.
*
* @param docElt the doc element
* @param relativeFileName the relative file name original value
* @return the relative file name
*/
default String resolveRelativeFileName(PackageElement docElt, String relativeFileName) {
return relativeFileName;
}
/**
* Render the source code of the {@code elt} argument.
*
* @param elt the element to render
* @param source the Java source of the element
* @return the rendered source
*/
String renderSource(ExecutableElement elt, String source);
/**
* Resolve a constructor link.
*
* @param elt the element linked to
* @return the resolved http link or null if the link cannot be resolved
*/
String resolveTypeLink(TypeElement elt);
/**
* Resolve a constructor link.
*
* @param elt the element linked to
* @return the resolved http link or null if the link cannot be resolved
*/
String resolveConstructorLink(ExecutableElement elt);
/**
* Resolve a method link.
*
* @param elt the element linked to
* @return the resolved http link or null if the link cannot be resolved
*/
String resolveMethodLink(ExecutableElement elt);
/**
* Resolve a field link.
*
* @param elt the element linked to
* @return the resolved http link or null if the link cannot be resolved
*/
String resolveFieldLink(VariableElement elt);
/**
* Resolve a label.
*
* @param elt the labelled element
* @param defaultLabel the default label
* @return the resolved label or null if a label cannot be resolved
*/
String resolveLabel(Element elt, String defaultLabel);
}
vertx-docgen-0.9.4/src/main/java/io/vertx/docgen/DocWriter.java 0000664 0000000 0000000 00000007645 14050521027 0024360 0 ustar 00root root 0000000 0000000 package io.vertx.docgen;
import java.io.IOException;
import java.io.Writer;
import java.lang.reflect.UndeclaredThrowableException;
import java.util.ArrayList;
import java.util.List;
import java.util.function.Supplier;
/**
* @author Julien Viet
*/
class DocWriter extends Writer {
private final StringBuilder delegate;
private final List