Java 14+ support

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "maven" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/maven.yml

@@ -0,0 +1,35 @@
+# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Java CI with Maven
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up JDK 17
+      uses: actions/setup-java@v3
+      with:
+        java-version: '17'
+        distribution: 'temurin'
+        cache: maven
+    - name: Build with Maven
+      run: mvn -B package --file pom.xml
+
+    # Optional: Uploads the full dependency graph to GitHub to improve the quality of Dependabot alerts this repository can receive
+    - name: Update dependency graph
+      uses: advanced-security/maven-dependency-submission-action@571e99aab1055c2e71a1e2309b9691de18d6b7d6

.gitignore

@@ -1,8 +1,11 @@
-/target/
-/.project
-/.settings
-/.classpath
-.idea
-/marklet.iml
-
-settings.xml
+/target/
+/.project
+/.settings
+/.classpath
+.idea
+/marklet.iml
+
+settings.xml
+
+dependency-reduced-pom.xml
+modulepath.txt

.java-version

@@ -1 +1 @@
-1.8
+14

.travis.yml

@@ -1,7 +1,7 @@
-language: java
-
-jdk:
-  - oraclejdk8
-
-script:
-  - mvn clean test
+language: java
+
+jdk:
+  - oraclejdk17
+
+script:
+  - mvn clean test

README.md

@@ -1,90 +1,166 @@
-# Marklet
-
-This is custom fork of
-useful [Marklet doclet](https://github.com/Faylixe/marklet/tree/master/javadoc/fr/faylixe/marklet)
-which main purpose was to generate a Javadoc in a markdown format.
-
-**Examples** :
-
-* [Marklet itself!](https://github.com/PandaTheGrim/marklet/tree/master/javadoc)
-
-In order to use it with Maven, adds the following configuration for the ``maven-javadoc-plugin``
-in your project ``POM`` :
-
-```xml
-
-<plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-javadoc-plugin</artifactId>
-    <version>${javadoc.plugin.version}</version>
-    <configuration>
-        <doclet>io.github.atlascommunity.marklet.Marklet</doclet>
-        <docletArtifact>
-            <groupId>io.github.atlascommunity</groupId>
-            <artifactId>marklet</artifactId>
-            <version>1.2.1</version>
-        </docletArtifact>
-        <reportOutputDirectory>./</reportOutputDirectory>
-        <destDir>./</destDir>
-        <additionalOptions>
-            <additionalOption>-d</additionalOption>
-            <additionalOption>doc</additionalOption>
-            <additionalOption>-e</additionalOption>
-            <additionalOption>md</additionalOption>
-        </additionalOptions>
-        <useStandardDocletOptions>false</useStandardDocletOptions>
-    </configuration>
-</plugin>
-```
-
-This will generate the javadoc report into the project directory under project subfolder ``doc``.
-
-## Java 8 doclint issues.
-
-If you are using Java 8 you may have some issues with doclint validation especially when using
-markdown blockquotes syntax. To deal with it, just add the following directive to your ``pom.xml``
-file to deactivate doclint :
-
-```xml
-
-<additionalOptions>
-    <additionalOption>-Xdoclint:none</additionalOption>
-</additionalOptions>
-```
-
-## Available doclet options
-
-| Option        | What it does                            | By default  |
-| ------------- |-----------------------------------------| ------------|
-| -d            | set output directory for documentation  | ./javadoc   |
-| -e            | set files extension                     | .md         |
-
-## Developing Marklet
-
-Marklet requires Apache Maven. In order to build, run
-
-```
-$ mvn install
-
-```
-
-In order to generate Markdown documentation for Marklet itself, run
-
-```
-$ mvn -P marklet-generation javadoc:javadoc
-```
-
-## License
-
-Marklet is licensed under the Apache License, Version 2.0
-
-## Current issues
-
-The current version is a still under development with the following feature missing :
-
-* Interfaces, inner classes, enumerations, and annotations has not been tested already and subject
-  to bug.
-
-* Migration from com.sun.javadoc to jdk.javadoc.doclet API
-
-* Version still needs testing
+# Marklet
+
+Marklet is a Doclet that plugs into `javadoc`. The purpose of Marklet is to generate Javadoc in Markdown format instead of
+the usual HTML that `javadoc` creates. 
+This version requires Java 14 or higher to run, but can document all lower source code versions.
+
+Currently working on the migration from `com.sun.javadoc` to the newer `jdk.javadoc.doclet` 
+API because the older classes are no longer supported on Java 12 and up. Still work in progress.
+
+**Examples** :
+
+* [Marklet documenting itself!](https://github.com/iSnow/marklet/tree/master/javadoc/README.md)
+
+## How to use
+
+You can run Marklet on the command line to generate one-shot documentation or add it to your `pom.xml` 
+so Markdown docs are created on Maven build. You probably can use it from Gradle, but since I am a Maven guy, I 
+don't know the syntax.
+
+The most important caveat is that you **have to** specify the Java packages (option `-subpackage`) you want to document
+and their location in the file system (option `-sourcepath`) correctly, otherwise no output will be generated
+(specifying `-sourcepath` alone is not sufficient).
+
+
+### Command-line use
+First run `mvn package` to build the doclet.
+
+Linux/macOS:
+```shell
+javadoc -docletpath ./target/marklet-2.0.0.jar \
+  -doclet io.github.atlascommunity.marklet.Marklet \
+  -cp ./target/marklet-2.0.0.jar \
+  -sourcepath ./src/main/java \
+  -subpackages io.github.atlascommunity.marklet
+```
+
+Windows:
+```shell
+javadoc -docletpath .\target\marklet-2.0.0.jar  -doclet io.github.atlascommunity.marklet.Marklet -cp .\target\marklet-2.0.0.jar -sourcepath .\src\main\java -subpackages io.github.atlascommunity.marklet
+```
+
+On both platforms, be sure to set `subpackages` toyour project packages qualified name and 
+`sourcepath` pointing to your sources.
+
+### Maven use
+In order to use it with Maven, add the following configuration for the ``maven-javadoc-plugin``
+in your project ``POM`` :
+
+```xml
+
+<profiles>
+    <profile>
+        <id>generate-markdown</id>
+        <activation>
+            <activeByDefault>false</activeByDefault>
+        </activation>
+        <build>
+            <plugins>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-javadoc-plugin</artifactId>
+                    <version>${maven-javadoc-plugin.version}</version>
+                    <configuration>
+                        <doclet>io.github.atlascommunity.marklet.Marklet</doclet>
+                        <docletArtifact>
+                            <groupId>io.github.atlascommunity</groupId>
+                            <artifactId>marklet</artifactId>
+                            <version>2.0.0</version>
+                        </docletArtifact>
+                        <reportOutputDirectory>./</reportOutputDirectory>
+                        <destDir>./</destDir>
+                        <useStandardDocletOptions>false</useStandardDocletOptions>
+                        <additionalOptions>
+                            <additionalOption>-e markdown</additionalOption>
+                        </additionalOptions>
+                        <show>private</show>
+                        <subpackages>io.github.atlascommunity.marklet</subpackages>
+                        <sourcepath>src/main/java/</sourcepath>
+                    </configuration>
+                </plugin>
+            </plugins>
+        </build>
+    </profile>
+</profiles>
+```
+
+This profile is not active by default, so the Markdown documentation would not get re-created with each Maven run,
+but if you type `mvn clean package -P generate-markdown`, it gets run. If you want to have it permanently active,
+set `activeByDefault` to `true`: 
+
+```xml
+<activation>
+     <activeByDefault>true</activeByDefault>
+ </activation>
+ ```
+
+Running from Maven, you may omit the `sourcepath` option, but be sure to set `subpackages` to
+your project packages qualified name. You may usually omit `reportOutputDirectory`, but not `destDir`.
+
+If you set `show` to `public`, no internals (protected/private objects) will be documented, and 
+your api-docs will be the public API.
+
+`useStandardDocletOptions` interferes with the working of Marklet, it must be set to `false`.
+
+This will generate the javadoc report into the project directory under project subfolder `javadoc` and use the 
+file extension `.markdown` ( the `-e` in the `additionalOptions` overrides the default extension `.md`).
+
+The Apache Maven site 
+[has more information](https://maven.apache.org/plugins/maven-javadoc-plugin/examples/alternate-doclet.html) 
+on how to use alternate doclets like Marklet in addition to the default HTML-generating `javadoc-plugin`.
+
+## Java 8 doclint issues.
+
+If you are using Java 8 you may have some issues with doclint validation especially when using
+Markdown blockquotes syntax. To deal with it, just add the following directive to your ``pom.xml``
+file to deactivate doclint :
+
+```xml
+
+<additionalOptions>
+    <additionalOption>-Xdoclint:none</additionalOption>
+</additionalOptions>
+```
+
+## Available doclet options
+
+| Option | LongOpt  | What it does                             | By default |
+|--------|----------|------------------------------------------|------------|
+| -e     |          | set files extension                      | .md        |
+| -i     |          | location of the source directory         |            |
+| -d     | -destDir | location of the target output directory  | .javadoc/  |
+
+## Developing Marklet
+
+To hack on Marklet and improve it, look at `Marklet.java` and use the `main()` method to get it to run
+in any IDE. The provided options allow you to run Marklet on its own source tree.
+
+
+In order to generate Markdown documentation for Marklet itself via Maven, run
+
+```
+$ mvn -P generate-markdown javadoc:javadoc
+```
+
+### Developer docs
+
+- [new jdk.javadoc.doclet API Docs](https://openjdk.org/groups/compiler/using-new-doclet.html)
+- [Javadoc for jdk.javadoc.doclet](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html)
+
+## License
+
+Marklet is licensed under the Apache License, Version 2.0
+
+## Current issues
+
+The current version is still under development with the following issues:
+
+* Interfaces, inner classes, enumerations, and annotations might have bugs.
+
+* read https://stackoverflow.com/questions/5592703/documented-annotation-in-java
+
+* Many modern (post Java-8) features will not be documented yet.
+
+* Migration from com.sun.javadoc to jdk.javadoc.doclet API (WIP)
+
+* Basically no unit tests

javadoc/README.md

@@ -1,7 +1,9 @@
-Project packages list
-=====================
-| Package                                                                                           |
-| ------------------------------------------------------------------------------------------------- |
-| [io.github.atlascommunity.marklet.constants](io/github/atlascommunity/marklet/constants/Index.md) |
-| [io.github.atlascommunity.marklet](io/github/atlascommunity/marklet/Index.md)                     |
-| [io.github.atlascommunity.marklet.pages](io/github/atlascommunity/marklet/pages/Index.md)         |
+List of packages
+================
+| Package                                                                                                   |
+| --------------------------------------------------------------------------------------------------------- |
+| [io.github.atlascommunity.marklet](io/github/atlascommunity/marklet/Index.md)                             |
+| [io.github.atlascommunity.marklet.util](io/github/atlascommunity/marklet/util/Index.md)                   |
+| [io.github.atlascommunity.marklet.pages](io/github/atlascommunity/marklet/pages/Index.md)                 |
+| [io.github.atlascommunity.marklet.constants](io/github/atlascommunity/marklet/constants/Index.md)         |
+| [io.github.atlascommunity.marklet.page_elements](io/github/atlascommunity/marklet/page_elements/Index.md) |

javadoc/io/github/atlascommunity/marklet/Index.md

@@ -1,12 +1,15 @@
-Package io.github.atlascommunity.marklet
-========================================
-**Marklet** is a custom Java Doclet which aims to generate a
- Javadoc in a markdown format which is ready to use in GitHub.
+Package _io.github.atlascommunity.marklet_
+==========================================
+**Marklet** is a custom Java Doclet.
 ---
+The purpose of Marklet is to generate Javadoc
+ in markdown format, which is especially useful on Github.
+
 Classes
 =======
-| Name                  |
-| --------------------- |
-| [Options](Options.md) |
-| [Marklet](Marklet.md) |
+| Name                              |
+| --------------------------------- |
+| [Marklet](Marklet.md)             |
+| [MarkletOption](MarkletOption.md) |
+| [Options](Options.md)             |