├── .gitignore ├── .travis.yml ├── LICENSE ├── NOTICE ├── README.adoc ├── pom.xml ├── sample ├── pom.xml └── src │ └── main │ └── java │ ├── people │ └── Person.java │ └── vehicles │ ├── AbstractVehicle.java │ ├── Car.java │ └── Vehicle.java └── src └── main └── java └── org └── asciidoctor ├── ExportDoclet.java ├── ExportRenderer.java ├── StandardAdapter.java └── package-info.java /.gitignore: -------------------------------------------------------------------------------- 1 | /.classpath 2 | /.project 3 | /.settings/ 4 | **/.idea/* 5 | *~ 6 | *.iml 7 | target 8 | tmp 9 | out 10 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: java 2 | sudo: false 3 | jdk: 4 | - oraclejdk7 5 | - openjdk7 6 | - openjdk6 7 | notifications: 8 | irc: "irc.freenode.org#asciidoctor" 9 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. -------------------------------------------------------------------------------- /NOTICE: -------------------------------------------------------------------------------- 1 | Copyright ${startYear}-${currentYear} ${name} 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at 6 | 7 | http://www.apache.org/licenses/LICENSE-2.0 8 | 9 | Unless required by applicable law or agreed to in writing, software 10 | distributed under the License is distributed on an "AS IS" BASIS, 11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | See the License for the specific language governing permissions and 13 | limitations under the License. -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = ExportDoclet 2 | 3 | image:https://travis-ci.org/johncarl81/exportdoclet.svg?branch=master["Build Status", link="https://travis-ci.org/johncarl81/exportdoclet"] 4 | 5 | A link:http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/doclet/overview.html[Doclet] that allows exporting javadoc 6 | comments containing link:http://asciidoctor.org[AsciiDoc] text to AsciiDoc files, enabling combining the javadocs into a broader AsciiDoc documentation for your Java project. 7 | 8 | Instead of exporting the javadoc comments to standard HTML files, the ExportDoclet exports them to AsciiDoc files, that in turn can be converted to any output format supported by the link:http://asciidoctor.org[AsciiDoctor toolchain]. 9 | 10 | Using the ExportDoclet, one can put together the source code documentation (javadocs written in AsciiDoc), quick start guides, user guides, FAQs and any other documentation for Java projects. 11 | 12 | AsciiDoc is a non-disturbing and clean markup language that you can use to write your javadocs. It provides a fast, elegant and professional way to write your documentation, beyond allowing the use of several new resources such as automatic code highlight and inclusion of snippets of code from your source files, providing a powerful way to keep your documentation updated with your code. 13 | 14 | ExportDoclet encourages developers to write meaninguful and expanded documentation that goes beyond the source code documentation, by enabling the integration with other plugins such as the link:https://github.com/asciidoctor/asciidoclet[AsciiDoclet] and link:https://github.com/asciidoctor/asciidoctor-maven-plugin[Maven AsciiDoctor Plugin]. 15 | 16 | == Building the ExportDoclet 17 | 18 | ExportDoclet is a Java Maven project that can be built directly from any IDE or using the following maven command: 19 | 20 | [source,bash] 21 | mvn clean install 22 | 23 | That will build the tool and install it at your local maven repository, usually at the .m2 directory 24 | inside your home directory. 25 | 26 | == How to use ExportDoclet 27 | There are different ways to use the ExportDoclet together with the javadoc tool, depending on your goal and project type. The next sub-sections present some of these ways. 28 | 29 | === Using the ExportDoclet with javadoc by command line 30 | 31 | To manually call the javadoc tool by command line using the ExportDoclet you have to follow 32 | the next steps in a terminal: 33 | 34 | - Enter into the folder that contains the java files with javadoc comments you want to export 35 | - Execute `javadoc -docletpath $DOCLETJAR -doclet org.asciidoctor.ExportDoclet -d $OUTPUTDIR *.java`, where: 36 | ** `$DOCLETJAR` is the path for the ExportDoclet jar file (that you built using the instructions in the previous section, or downloaded from link:https://maven-badges.herokuapp.com/maven-central/org.asciidoctor/exportdoclet[maven central] or link:https://bintray.com/asciidoctor/maven/asciidoclet[bintray]) 37 | ** `$OUTPUTDIR` is where you want to save the exported asciidoc files. 38 | 39 | === Using ExportDoclet with Maven javadoc plugin 40 | 41 | Using the ExportDoclet with Maven is pretty simple. You can include the maven-javadoc-plugin configuration inside the `` section of project's pom.xml file, defining the required configuration for the javadoc command line tool that was used above. 42 | 43 | The sub-sections below present some distinct configurations. 44 | 45 | ==== Generating only the AsciiDoc files 46 | 47 | To generate just the AsciiDoc files and ignore the genration of the default HTML files, you can include the following code to the `` section of your project's pom.xml. 48 | 49 | [source,xml] 50 | -- 51 | 52 | org.apache.maven.plugins 53 | maven-javadoc-plugin 54 | 2.10.4 55 | 56 | org.asciidoctor.ExportDoclet 57 | 58 | org.asciidoctor 59 | exportdoclet 60 | 1.5.4-SNAPSHOT 61 | 62 | true 63 | 64 | 65 | -- 66 | 67 | Now, to generate the javadocs in AsciiDoc files you can execute the `javadoc:javadoc` goal in Maven, using your IDE or the command line inside your project root directory: 68 | 69 | [source,bash] 70 | mvn javadoc:javadoc 71 | 72 | The exported javadocs to AsciiDoc files will be found at target/site/apidocs directory. 73 | 74 | ==== Generating both the AsciiDoc and default HTML files 75 | 76 | If you want to generate both the AsciiDoc and HTML files, that requires two different configurations for the maven-javadoc-plugin, 77 | as exemplified below. That includes the link:https://github.com/asciidoctor/asciidoclet[AsciiDoclet] to enable converting 78 | the AsciiDoclet tags inside your javadoc comments to HTML tags. 79 | 80 | [source,xml] 81 | -- 82 | 83 | org.apache.maven.plugins 84 | maven-javadoc-plugin 85 | 2.10.4 86 | 87 | 88 | 89 | html 90 | package 91 | 92 | javadoc 93 | 94 | 95 | org.asciidoctor.Asciidoclet 96 | 97 | org.asciidoctor 98 | asciidoclet 99 | 1.5.4 100 | 101 | 102 | --base-dir ${project.basedir} 103 | --attribute "name=${project.name}" 104 | --attribute "version=${project.version}" 105 | 106 | 107 | 108 | 109 | 110 | asciidoc 111 | package 112 | 113 | javadoc 114 | 115 | 116 | org.asciidoctor.ExportDoclet 117 | 118 | org.asciidoctor 119 | exportdoclet 120 | 1.5.4-SNAPSHOT 121 | 122 | true 123 | 124 | -d "${project.build.directory}/site/asciidocs" 125 | 126 | 127 | 128 | 129 | 130 | -- 131 | 132 | Now, to generate the javadocs both in AsciiDoc and HTML files, you can execute the `package` goal in Maven, using your IDE or the command line inside your project root directory: 133 | 134 | [source,bash] 135 | mvn clean package 136 | 137 | You can see a link:sample[sample project] that has some java files with javadocs containing AsciiDoc, and that has everything configured in the pom.xml. 138 | 139 | == How to use the generated AsciiDoc Files 140 | 141 | After using the ExportDoclet to export the javadoc comments written in AsciiDoc, you can put together your entire project documentation (javadocs, quick start guides, user guides, FAQs, etc) and exporting them to several different formats such as beautiful HTMLs, PDF, epub or any other format supported by link:http://asciidoctor.org[AsciiDoctor]. 142 | 143 | In order to accomplish that, you can use the link:https://github.com/asciidoctor/asciidoctor-maven-plugin[Maven AsciiDoctor Plugin] to automate the process of collecting all AsciiDoc files, that compound the entire project documentation, and export them to any deployment format such as HTML or PDF. 144 | 145 | == Contributors 146 | 147 | - link:http://twitter.com/manoelcampos[Manoel Campos da Silva Filho] 148 | 149 | == Additional References 150 | - link:http://www.manpagez.com/man/1/javadoc/[The javadoc Command Line Manual] 151 | - link:http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html[The javadoc Tool Home Page] 152 | - link:https://maven.apache.org/plugins/maven-javadoc-plugin[Maven javadoc Plugin] 153 | - link:https://github.com/asciidoctor/asciidoclet[AsciiDoclet] 154 | - link:https://github.com/asciidoctor/asciidoctor-maven-plugin[Maven AsciiDoctor Plugin] 155 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 4.0.0 5 | 6 | org.asciidoctor 7 | exportdoclet 8 | jar 9 | 1.5.4-SNAPSHOT 10 | 11 | Export Doclet 12 | 13 | 14 | org.sonatype.oss 15 | oss-parent 16 | 7 17 | 18 | 19 | http://asciidoctor.org 20 | Exportdoclet is a Javadoc Doclet that exports javadocs written in AsciiDoc to adoc files. 21 | 22 | 23 | 24 | Apache 2.0 25 | http://www.apache.org/licenses/LICENSE-2.0.txt 26 | 27 | 28 | 29 | 30 | http://github.com/johncarl81/exportdoclet 31 | scm:git:git@github.com:johncarl81/exportdoclet.git 32 | scm:git:git@github.com:johncarl81/exportdoclet.git 33 | 34 | 35 | 36 | 37 | bintray-asciidoctor-maven-exportdoclet 38 | asciidoctor-maven-exportdoclet 39 | https://api.bintray.com/maven/asciidoctor/maven/exportdoclet 40 | 41 | 42 | 43 | 44 | 45 | org.asciidoctor 46 | asciidoctorj 47 | 1.5.3 48 | 49 | 50 | com.sun.tools 51 | tools 52 | ${java.version} 53 | system 54 | ${java.home}/../lib/tools.jar 55 | 56 | 57 | org.slf4j 58 | slf4j-simple 59 | 1.7.7 60 | 61 | 62 | com.google.guava 63 | guava 64 | 17.0 65 | 66 | 67 | junit 68 | junit 69 | 4.11 70 | test 71 | 72 | 73 | org.mockito 74 | mockito-all 75 | 1.9.5 76 | test 77 | 78 | 79 | org.powermock 80 | powermock-module-junit4 81 | 1.5 82 | test 83 | 84 | 85 | org.powermock 86 | powermock-api-mockito 87 | 1.5 88 | test 89 | 90 | 91 | org.hamcrest 92 | hamcrest-library 93 | 1.3 94 | test 95 | 96 | 97 | 98 | 99 | 100 | 101 | org.apache.maven.plugins 102 | maven-compiler-plugin 103 | 3.1 104 | 105 | 1.6 106 | 1.6 107 | 108 | 109 | 110 | org.apache.maven.plugins 111 | maven-source-plugin 112 | 2.2.1 113 | 114 | 115 | attach-sources 116 | 117 | jar 118 | 119 | 120 | 121 | 122 | 123 | org.apache.maven.plugins 124 | maven-javadoc-plugin 125 | 2.9 126 | 127 | 128 | attach-javadocs 129 | 130 | jar 131 | 132 | 133 | 134 | 135 | 1.7 136 | org.asciidoctor.ExportDoclet 137 | 138 | org.asciidoctor 139 | exportdoclet 140 | ${project.version} 141 | 142 | 143 | 144 | 145 | com.mycila.maven-license-plugin 146 | maven-license-plugin 147 | 1.9.0 148 | 149 |
NOTICE
150 | 151 | SLASHSTAR_STYLE 152 | 153 | 154 | **/*.java 155 | **/*.xml 156 | 157 | 158 | **/.*/** 159 | target/** 160 | **/AndroidManifest.xml 161 | 162 | 163 | 2013 164 | 2016 165 | John Ericksen 166 | 167 | true 168 | true 169 | 170 | 171 | 172 | maven-assembly-plugin 173 | 2.5.5 174 | 175 | 176 | jar-with-dependencies 177 | 178 | ${project.build.finalName}-all 179 | false 180 | 181 | 182 | 183 | make-assembly 184 | package 185 | 186 | single 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | -------------------------------------------------------------------------------- /sample/pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | 4.0.0 6 | 7 | org.asciidoctor 8 | exportdoclet-sample 9 | 1.0.0-SNAPSHOT 10 | 11 | 12 | A sample project with a set of classes used just 13 | to demonstrate how the org.asciidoctor.exportdoclet plugin exports 14 | the javadoc from the project java files as AsciiDoc files. 15 | 16 | 17 | 18 | 19 | Manoel Campos da Silva Filho 20 | http://twitter.com/manoelcampos 21 | 22 | 23 | 24 | 25 | UTF-8 26 | 1.8 27 | 28 | 29 | 30 | 31 | 32 | org.apache.maven.plugins 33 | maven-compiler-plugin 34 | 3.6.1 35 | 36 | ${project.build.sourceFormat} 37 | ${project.build.sourceFormat} 38 | 39 | 40 | 41 | 49 | 50 | 51 | org.apache.maven.plugins 52 | maven-javadoc-plugin 53 | 2.10.4 54 | 55 | org.asciidoctor.ExportDoclet 56 | 57 | org.asciidoctor 58 | exportdoclet 59 | 1.5.4-SNAPSHOT 60 | 61 | true 62 | 63 | 64 | 65 | 66 | 73 | 74 | 75 | org.apache.maven.plugins 76 | maven-javadoc-plugin 77 | 2.10.4 78 | 79 | 80 | 81 | html 82 | package 83 | 84 | javadoc 85 | 86 | 87 | org.asciidoctor.Asciidoclet 88 | 89 | org.asciidoctor 90 | asciidoclet 91 | 1.5.4 92 | 93 | 94 | --base-dir ${project.basedir} 95 | --attribute "name=${project.name}" 96 | --attribute "version=${project.version}" 97 | 98 | 99 | 100 | 101 | 102 | asciidoc 103 | package 104 | 105 | javadoc 106 | 107 | 108 | org.asciidoctor.ExportDoclet 109 | 110 | org.asciidoctor 111 | exportdoclet 112 | 1.5.4-SNAPSHOT 113 | 114 | true 115 | 116 | -d "${project.build.directory}/site/asciidocs" 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | -------------------------------------------------------------------------------- /sample/src/main/java/people/Person.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package people; 17 | 18 | /** 19 | * An interface to represent different kinds of People. 20 | * 21 | * @author http://twitter.com/manoelcampos[Manoel Campos da Silva Filho] 22 | * @see https://en.wikipedia.org/wiki/People[People at Wikipedia] 23 | */ 24 | public interface Person { 25 | /** 26 | * Gets the person's name. 27 | * @return the name of the person 28 | */ 29 | String getName(); 30 | } 31 | -------------------------------------------------------------------------------- /sample/src/main/java/vehicles/AbstractVehicle.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package vehicles; 17 | 18 | import people.Person; 19 | 20 | import java.time.LocalDate; 21 | 22 | /** 23 | * An abstract class for implementing different kinds of link:Vehicle[]. 24 | * 25 | * @author http://twitter.com/manoelcampos[Manoel Campos da Silva Filho] 26 | */ 27 | public class AbstractVehicle implements Vehicle { 28 | /** 29 | * The year the vehicle was manufactured. 30 | */ 31 | private int manufacturingYear; 32 | 33 | /** 34 | * The link:Person[] who owns the vehicle. 35 | */ 36 | private Person owner; 37 | 38 | @Override 39 | public int getManufacturingYear() { 40 | return manufacturingYear; 41 | } 42 | 43 | @Override 44 | public void setManufacturingYear(int year) { 45 | this.manufacturingYear = year; 46 | } 47 | 48 | @Override 49 | public Person getOwner() { 50 | return owner; 51 | } 52 | 53 | @Override 54 | public void setOwner(Person owner) { 55 | this.owner = owner; 56 | } 57 | 58 | @Override 59 | public int getYears() { 60 | return LocalDate.now().minusYears(manufacturingYear).getYear(); 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /sample/src/main/java/vehicles/Car.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package vehicles; 17 | 18 | /** 19 | * A Car represents a terrestrial link:Vehicle[] 20 | * with 4 wheels. 21 | * 22 | * @author http://twitter.com/manoelcampos[Manoel Campos da Silva Filho] 23 | */ 24 | public class Car extends AbstractVehicle { 25 | /** 26 | * An enumeration to represent left and right sides. 27 | */ 28 | enum Side {LEFT, RIGHT} 29 | 30 | private Side driverSide; 31 | 32 | /** 33 | * Gets the side where the driver seats. 34 | * @return the driver's seat side 35 | */ 36 | public Side getDriverSide() { 37 | return driverSide; 38 | } 39 | 40 | /** 41 | * Sets the side where the driver seats. 42 | * @param driverSide the driver's seat side to set 43 | */ 44 | public void setDriverSide(Side driverSide) { 45 | this.driverSide = driverSide; 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /sample/src/main/java/vehicles/Vehicle.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package vehicles; 17 | 18 | import people.Person; 19 | 20 | /** 21 | * An interface to represent different kinds of Vehicles such as: 22 | * - cars 23 | * - motorcicles 24 | * - airplanes 25 | * - boats 26 | * 27 | * @author http://twitter.com/manoelcampos[Manoel Campos da Silva Filho] 28 | * @see https://en.wikipedia.org/wiki/Vehicle[Vehicles at Wikipedia] 29 | */ 30 | public interface Vehicle { 31 | /** 32 | * Gets the year the vehicle was manufactured 33 | * @return the manufacturing year 34 | */ 35 | int getManufacturingYear(); 36 | 37 | /** 38 | * Sets the year the vehicle was manufactured 39 | * @param year the year to set 40 | */ 41 | void setManufacturingYear(int year); 42 | 43 | /** 44 | * Gets the link:Person[] that owns the vehicle. 45 | * @return the vehicle's owner 46 | */ 47 | Person getOwner(); 48 | 49 | /** 50 | * Sets the link:Person[] who owns the vehicle. 51 | * @param owner the vehicle's owner 52 | */ 53 | void setOwner(Person owner); 54 | 55 | /** 56 | * Gets the vehicle age in number of years since it was manufactured. 57 | * @return the vehicle age in years 58 | */ 59 | int getYears(); 60 | } 61 | -------------------------------------------------------------------------------- /src/main/java/org/asciidoctor/ExportDoclet.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package org.asciidoctor; 17 | 18 | import com.sun.javadoc.DocErrorReporter; 19 | import com.sun.javadoc.Doclet; 20 | import com.sun.javadoc.LanguageVersion; 21 | import com.sun.javadoc.RootDoc; 22 | 23 | /** 24 | * A link:Doclet[] that exports javadoc comments containing AsciiDoc text to AsciiDoc files, 25 | * instead of specific final formats such as HTML. 26 | * 27 | * @author John Ericksen 28 | * @see ExportRenderer 29 | */ 30 | public class ExportDoclet extends Doclet { 31 | 32 | private final ExportRenderer renderer; 33 | 34 | /** 35 | * Starts the doclet. 36 | * @param rootDoc the root of the program structure information. 37 | * From this root all other program structure information can be extracted. 38 | * @return true if the doclet was started successfuly, false otherwise 39 | * @see Doclet#start(RootDoc) 40 | */ 41 | @SuppressWarnings("UnusedDeclaration") 42 | public static boolean start(RootDoc rootDoc) { 43 | return new ExportDoclet(rootDoc).render(); 44 | } 45 | 46 | /** 47 | * Creates a ExportDoclet to export javadoc comments to AsciiDoc files. 48 | * 49 | * @param rootDoc the root of the program structure information. 50 | * From this root all other program structure information can be extracted. 51 | */ 52 | public ExportDoclet(RootDoc rootDoc) { 53 | this.renderer = new ExportRenderer(rootDoc); 54 | } 55 | 56 | /** 57 | * Validates command line options. 58 | * 59 | * @param options the array of given options 60 | * @param errorReporter an object that allows printing error messages for invalid options 61 | * @return true if the options are valid, false otherwise 62 | * @see Doclet#validOptions(String[][], DocErrorReporter) 63 | */ 64 | @SuppressWarnings("UnusedDeclaration") 65 | public static boolean validOptions(String[][] options, DocErrorReporter errorReporter) { 66 | return new StandardAdapter().validOptions(options, errorReporter); 67 | } 68 | 69 | /** 70 | * Gets the number of arguments that a given command line option must contain. 71 | * @param option the command line option 72 | * @return the number of arguments required for the given option 73 | * @see Doclet#optionLength(String) 74 | */ 75 | @SuppressWarnings("UnusedDeclaration") 76 | public static int optionLength(String option) { 77 | return new StandardAdapter().optionLength(option); 78 | } 79 | 80 | /** 81 | * Return the version of the Java Programming Language supported 82 | * by this doclet. 83 | * @return the Java language supported version 84 | * @see Doclet#languageVersion() 85 | */ 86 | @SuppressWarnings("UnusedDeclaration") 87 | public static LanguageVersion languageVersion() { 88 | return LanguageVersion.JAVA_1_5; 89 | } 90 | 91 | /** 92 | * Renders the javadoc documentation for all elements inside the link:RootDoc[] object 93 | * received by this doclet. 94 | * @return true if the link:RootDoc[] was rendered successfully, false otherwise 95 | */ 96 | private boolean render(){ 97 | return renderer.render(); 98 | } 99 | } 100 | -------------------------------------------------------------------------------- /src/main/java/org/asciidoctor/ExportRenderer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package org.asciidoctor; 17 | 18 | import com.sun.javadoc.AnnotationTypeDoc; 19 | import com.sun.javadoc.ClassDoc; 20 | import com.sun.javadoc.MemberDoc; 21 | import com.sun.javadoc.PackageDoc; 22 | import com.sun.javadoc.RootDoc; 23 | 24 | import java.io.File; 25 | import java.io.FileNotFoundException; 26 | import java.io.FileOutputStream; 27 | import java.io.OutputStreamWriter; 28 | import java.io.PrintWriter; 29 | import java.util.Arrays; 30 | import java.util.HashSet; 31 | import java.util.Set; 32 | 33 | /** 34 | * A renderer class that actually exports javadoc comments containing AsciiDoc text to AsciiDoc files, 35 | * instead of specific final formats such as HTML. 36 | * It is used when the link:ExportDoclet[] is started. 37 | * 38 | * @author John Ericksen 39 | */ 40 | public class ExportRenderer { 41 | /** 42 | * Holds the root of the program structure information. 43 | * From this root all other program structure information can be extracted. 44 | */ 45 | private final RootDoc rootDoc; 46 | 47 | public ExportRenderer(RootDoc rootDoc){ 48 | this.rootDoc = rootDoc; 49 | } 50 | 51 | /** 52 | * Renders classes and packages javadocs, inside a link:RootDoc[] object, to AsciiDoc files. 53 | * 54 | * @return true if successful, false otherwise 55 | */ 56 | public boolean render() { 57 | Set packages = new HashSet(); 58 | for (ClassDoc doc : rootDoc.classes()) { 59 | packages.add(doc.containingPackage()); 60 | renderClass(doc); 61 | } 62 | 63 | for (PackageDoc doc : packages) { 64 | renderPackage(doc); 65 | //renderer.renderDoc(doc); 66 | } 67 | 68 | return true; 69 | } 70 | 71 | /** 72 | * Renders a class documentation to an AsciiDoc file. 73 | * 74 | * @param doc the class documentation object 75 | */ 76 | private void renderClass(ClassDoc doc) { 77 | try { 78 | PrintWriter writer = getWriter(doc.containingPackage(), doc.name()); 79 | if (doc.position() != null) { 80 | outputText(doc.name(), doc.getRawCommentText(), writer); 81 | } 82 | for (MemberDoc member : doc.fields(false)) { 83 | outputText(member.name(), member.getRawCommentText(), writer); 84 | } 85 | for (MemberDoc member : doc.constructors(false)) { 86 | outputText(member.name(), member.getRawCommentText(), writer); 87 | } 88 | for (MemberDoc member : doc.methods(false)) { 89 | outputText(member.name(), member.getRawCommentText(), writer); 90 | } 91 | for (MemberDoc member : doc.enumConstants()) { 92 | outputText(member.name(), member.getRawCommentText(), writer); 93 | } 94 | if (doc instanceof AnnotationTypeDoc) { 95 | for (MemberDoc member : ((AnnotationTypeDoc) doc).elements()) { 96 | outputText(member.name(), member.getRawCommentText(), writer); 97 | } 98 | } 99 | writer.flush(); 100 | } catch (FileNotFoundException e) { 101 | e.printStackTrace(); 102 | } 103 | } 104 | 105 | /** 106 | * Renders a package documentation to an AsciiDoc file. 107 | * 108 | * @param doc the package documentation object 109 | */ 110 | private void renderPackage(PackageDoc doc){ 111 | try { 112 | PrintWriter writer = getWriter(doc, "package-info"); 113 | writer.println(doc.name()); 114 | if (doc.position() != null) { 115 | outputText(doc.name(), doc.getRawCommentText(), writer); 116 | } 117 | if (doc instanceof AnnotationTypeDoc) { 118 | for (MemberDoc member : ((AnnotationTypeDoc) doc).elements()) { 119 | outputText(member.name(), member.getRawCommentText(), writer); 120 | } 121 | } 122 | writer.flush(); 123 | } catch (FileNotFoundException e) { 124 | e.printStackTrace(); 125 | } 126 | } 127 | 128 | /** 129 | * Exports a javadoc comment using a given link:PrintWriter[], surrounding 130 | * it by a AsciiDoc tag with a specific name. 131 | * 132 | * @param tag the name of the tag to surround the javadoc comment into the AsciiDoc file 133 | * @param comment the javadoc comment to export 134 | * @param writer the link:PrintWriter[] to be used to export the javadoc comment to an AsciiDoc file 135 | */ 136 | private void outputText(String tag, String comment, PrintWriter writer) { 137 | writer.println("// tag::" + tag + "[]"); 138 | writer.println(cleanJavadocInput(comment)); 139 | writer.println("// end::" + tag + "[]"); 140 | } 141 | 142 | private String cleanJavadocInput(String input) { 143 | return input.trim() 144 | .replaceAll("\n ", "\n") // Newline space to accommodate javadoc newlines. 145 | .replaceAll("(?m)^( *)\\*\\\\/$", "$1*/"); // Multi-line comment end tag is translated into */. 146 | } 147 | 148 | /** 149 | * Gets a link:PrintWriter[] to export the documentation of a class or package 150 | * to an AsciiDoc file. 151 | * 152 | * @param packageDoc the package documentation object that will be the package that the documentation 153 | * is being exported or the package of the class that its documentation 154 | * is being exported 155 | * @param name the name of the AsciiDoc file to export the documentation to 156 | */ 157 | private PrintWriter getWriter(PackageDoc packageDoc, String name) throws FileNotFoundException { 158 | File packageDirectory = new File(getOutputDir() + packageDoc.name().replace('.', File.separatorChar)); 159 | if(!packageDirectory.exists() && !packageDirectory.mkdirs()){ 160 | throw new RuntimeException("The directory was not created due to unknown reason."); 161 | } 162 | 163 | File file = new File(packageDirectory, name + ".adoc"); 164 | return new PrintWriter(new OutputStreamWriter(new FileOutputStream(file))); 165 | } 166 | 167 | /** 168 | * Gets the output directory passed as a command line argument to javadoc tool. 169 | * @return the output directory to export the javadocs 170 | */ 171 | private String getOutputDir() { 172 | for (String[] option : rootDoc.options()) { 173 | if(option.length == 2 && option[0].equals("-d")) { 174 | return includeTrailingDirSeparator(option[1]); 175 | } 176 | } 177 | 178 | return ""; 179 | } 180 | 181 | /** 182 | * Adds a trailing slash at the end of a path if it doesn't have one yet. 183 | * The trailing slash type is system-dependent and will be accordingly selected. 184 | * 185 | * @param path the path to include a trailing slash 186 | * @return the path with a trailing slash if there wasn't one and the path is not empty, 187 | * the original path otherwise 188 | */ 189 | private String includeTrailingDirSeparator(String path){ 190 | if(path.trim().isEmpty()) { 191 | return path; 192 | } 193 | 194 | if(path.charAt(path.length()-1) != File.separatorChar){ 195 | return path + File.separator; 196 | } 197 | 198 | return path; 199 | } 200 | 201 | } 202 | -------------------------------------------------------------------------------- /src/main/java/org/asciidoctor/StandardAdapter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package org.asciidoctor; 17 | 18 | import com.sun.javadoc.DocErrorReporter; 19 | import com.sun.javadoc.Doclet; 20 | import com.sun.javadoc.RootDoc; 21 | import com.sun.tools.doclets.standard.Standard; 22 | 23 | /** 24 | * Adapter class to use the link:Standard[] Javadoc link:Doclet[] in a non-static context. 25 | * 26 | * @author John Ericksen 27 | */ 28 | public class StandardAdapter { 29 | 30 | public int optionLength(String option) { 31 | return Standard.optionLength(option); 32 | } 33 | 34 | public boolean start(RootDoc rootDoc) { 35 | return Standard.start(rootDoc); 36 | } 37 | 38 | public boolean validOptions(String[][] options, DocErrorReporter errorReporter) { 39 | return Standard.validOptions(options, errorReporter); 40 | } 41 | } 42 | -------------------------------------------------------------------------------- /src/main/java/org/asciidoctor/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2013-2016 John Ericksen 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Provides the classes that implement the link:ExportDoclet[] to extract javadoc comments, 19 | * written in AsciiDoc, from java source files and export then to AsciiDoc files. 20 | * @author John Ericksen 21 | */ 22 | package org.asciidoctor; --------------------------------------------------------------------------------