Commit cded98c3 authored by Brian Long's avatar Brian Long
Browse files

Merge branch 'develop' into stable

parents 3846946b 1d4e323c

README.md

+39 −5
Changes for README.md: 39 added lines, 5 removed lines.
Original line number Diff line number Diff line 
# Activiti API Doclet



This library provides a Javadoc Doclet for the generation of Activiti API documentation.  You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR project.  That plugin should be configured to use this doclet.  See the snippet below.

This library provides a Javadoc Doclet for the generation of Activiti API documentation.



## Generating Documentation



The generated documentation is formatted in Markdown.  It works great when checked into your project stored in GitHub, Bitbucket, or similar Git-based web interface.



You can use it by defining a Javadoc plugin in your Activiti extension Maven JAR project.  That plugin should be configured to use this doclet.  See the snippet below.



```xml

<profile>
@@ -10,7 +16,7 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume 
			<plugin>

				<groupId>org.apache.maven.plugins</groupId>

				<artifactId>maven-javadoc-plugin</artifactId>

				<version>3.4.1</version>

				<version>3.8.0</version>

				<executions>

					<execution>

						<id>generate-doclet</id>
@@ -21,15 +27,16 @@ This library provides a Javadoc Doclet for the generation of Activiti API docume 
							<docletArtifact>

								<groupId>com.inteligr8.activiti</groupId>

								<artifactId>activiti-api-doclet</artifactId>

								<version>1.0.4</version>

								<version>1.1-SNAPSHOT</version>

							</docletArtifact>

							<useStandardDocletOptions>false</useStandardDocletOptions>

							<destDir>apidocs</destDir>

							<reportOutputDirectory>${basedir}</reportOutputDirectory>

							<additionalOptions>

								<additionalOption>--title 'API Documentation'</additionalOption>

								<additionalOption>--apiName '${project.name}</additionalOption>

							</additionalOptions>

					        <sourceFileIncludes>**/*.java</sourceFileIncludes>

							<destDir>apidocs</destDir>

							<reportOutputDirectory>${basedir}</reportOutputDirectory>

						</configuration>

					</execution>

				</executions>
@@ -46,3 +53,30 @@ mvn -Papidocs generate-resources 
```



The documentation will be placed in `<reportOutputDirectory>/<destDir>`.



## Special Considerations



This supports many standard tags used in JavaDoc comments.  This includes support for the following:



| Tag           | Classes/Interfaces | Methods |

| ------------- |:------------------:|:-------:|

| `@author`     | ✓                  | ✓       |

| `@since`      | ✓                  | ✓       |

| `@version`    | ✓                  | ✓       |

| `@deprecated` | ✓                  | ✓       |

| `@see`        | ✓                  | ✓       |

| `@param`      |                    | ✓       |

| `@return`     |                    | ✓       |

| `@throws`     |                    | ✓       |



If the `@see` tag contains a `#` (e.g. `beanId#method`) then it will hyperlink to the specified bean and method documentation.  If you use `beanId#` it will hyperlink to the bean documentation.  You can use `beanId#delegate` if you want to hyperlink tot he bean and delegate method documentation.



If the `@throws` tag is a `BPMNError`, the next term is expected to be the error code, followed by the standard comment.  For example, `@throws BPMNError http-404 Not found`.



The following additional non-standard tags are supported as well:



| Tag           | Description |

| ------------- | ----------- |

| `@field`      | A BPMN field name followed by the standard comment.  This field may be used by the execution. |

| `@varIn`      | An Activiti variable name followed by the standard comment.  This variable may be used by the execution. |

| `@varOut`     | An Activiti variable name followed by the standard comment.  This variable may be set during the execution. |

pom.xml

+14 −7
Changes for pom.xml: 14 added lines, 7 removed lines.
Original line number Diff line number Diff line
@@ -41,7 +41,7 @@ 
    	<maven.compiler.release>11</maven.compiler.release>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        

        <spring.version>5.3.24</spring.version>

        <spring.version>6.2.2</spring.version>

    </properties>

    

    <dependencies>
@@ -53,7 +53,7 @@ 
    	<dependency>

    		<groupId>org.freemarker</groupId>

    		<artifactId>freemarker</artifactId>

    		<version>2.3.31</version>

    		<version>2.3.34</version>

    	</dependency>

    	<dependency>

    		<groupId>org.slf4j</groupId>
@@ -63,16 +63,24 @@ 
    </dependencies>

    

    <build>

		<pluginManagement>

			<plugins>

				<plugin>

					<artifactId>maven-invoker-plugin</artifactId>

					<version>3.9.0</version>

				</plugin>

			</plugins>

		</pluginManagement>

    	<plugins>

			<plugin>

				<artifactId>maven-invoker-plugin</artifactId>

				<version>3.2.2</version>

				<configuration>

					<projectsDirectory>${basedir}/src/it</projectsDirectory>

					<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>

					<localRepositoryPath>${project.build.directory}/it-repo</localRepositoryPath>

					<mavenHome>${env.MAVEN_HOME}</mavenHome>

					<debug>true</debug>

					<skipInvocation>${skipTests}</skipInvocation>

					<properties>

						<project.main.basedir>${basedir}</project.main.basedir>

					</properties>
@@ -98,7 +106,7 @@ 
				<dependency>

					<groupId>org.activiti</groupId>

					<artifactId>activiti-engine</artifactId>

					<version>7.4.0</version>

					<version>7.11.1</version>

				</dependency>

    		</dependencies>

			<repositories>
@@ -119,7 +127,6 @@ 
				<plugins>

					<plugin>

						<artifactId>maven-invoker-plugin</artifactId>

						<version>3.2.2</version>

						<executions>

							<execution>

								<id>run-its</id>
@@ -158,7 +165,7 @@ 
					</plugin>

					<plugin>

						<artifactId>maven-javadoc-plugin</artifactId>

						<version>3.4.1</version>

						<version>3.11.2</version>

						<executions>

							<execution>

								<id>javadoc</id>
@@ -184,7 +191,7 @@ 
					<plugin>

						<groupId>org.sonatype.plugins</groupId>

						<artifactId>nexus-staging-maven-plugin</artifactId>

						<version>1.6.13</version>

						<version>1.7.0</version>

						<configuration>

							<serverId>ossrh</serverId>

							<nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>

src/it/base/pom.xml

+6 −3
Changes for src/it/base/pom.xml: 6 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -22,12 +22,12 @@ 
		<dependency>

			<groupId>org.activiti</groupId>

			<artifactId>activiti-engine</artifactId>

			<version>7.4.0</version>

			<version>7.11.1</version>

		</dependency>

		<dependency>

			<groupId>org.springframework</groupId>

			<artifactId>spring-context</artifactId>

			<version>5.3.24</version>

			<version>6.2.2</version>

		</dependency>

	</dependencies>
@@ -36,7 +36,7 @@ 
			<plugin>

				<groupId>org.apache.maven.plugins</groupId>

				<artifactId>maven-javadoc-plugin</artifactId>

				<version>3.4.1</version>

				<version>3.11.2</version>

				<executions>

					<execution>

						<id>generate-doclet</id>
@@ -56,6 +56,9 @@ 
								<additionalOption>--title 'Example Title'</additionalOption>

								<additionalOption>--apiName '${project.name}'</additionalOption>

							</additionalOptions>



							<!-- This is required in maven-javadoc-plugin v3.5+ -->

							<sourceFileIncludes>**/*.java</sourceFileIncludes>

						</configuration>

					</execution>

				</executions>

src/it/base/src/main/java/TestExtraTagsBean.java

0 → 100644
+23 −0
Changes for src/it/base/src/main/java/TestExtraTagsBean.java: 23 added lines, 0 removed lines.
Original line number Diff line number Diff line 


import org.springframework.stereotype.Component;



/**

 * This is an example comment for the class TestExtraTagsBean.

 * 

 * @author brian@inteligr8.com

 * @version 1.0

 */

@Component("extra")

public class TestExtraTagsBean {

	

	/**

	 * This is an example comment for the method apiMethod1()

	 * 

	 * @field field1 An example field comment.

	 * @varIn var1 An example input variable comment.

	 * @varOut var2 An example output variable comment.

	 */

	public void apiMethod1() {

	}



}

src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java

+15 −1
Changes for src/main/java/com/inteligr8/activiti/doclet/ActivitiDocFilter.java: 15 added lines, 1 removed line.
Original line number Diff line number Diff line
@@ -28,6 +28,8 @@ import javax.lang.model.element.ElementKind; 
import javax.lang.model.element.ExecutableElement;

import javax.lang.model.element.Modifier;

import javax.lang.model.element.TypeElement;

import javax.lang.model.type.DeclaredType;

import javax.lang.model.type.TypeKind;

import javax.lang.model.type.TypeMirror;



import org.slf4j.Logger;
@@ -102,7 +104,9 @@ class ActivitiDocFilter { 
		Set<String> taskListenerMethodElements = new HashSet<>(5);



		// getAllTypeElements() will get inherited interfaces

		for (TypeMirror interfaceType : classElement.getInterfaces()) {

		TypeElement superclassElement = classElement;

		while (superclassElement != null) {

			for (TypeMirror interfaceType : superclassElement.getInterfaces()) {

				this.logger.trace("Found interface '{}' on bean '{}'", interfaceType, beanId);

				

				switch (interfaceType.toString()) {
@@ -121,6 +125,16 @@ class ActivitiDocFilter { 
				}

			}



			TypeMirror superclassMirror = superclassElement.getSuperclass();

			if (superclassMirror == null) {

				superclassElement = null;

			} else if (superclassMirror.getKind() != TypeKind.DECLARED) {

				superclassElement = null;

			} else {

				superclassElement = (TypeElement) ((DeclaredType) superclassMirror).asElement();

			}

		}

		

		this.logger.info("delegates: {}", delegateMethodElements);

		

		// getAllMembers() will get inherited methods