[docs] Prepare for the addition of hyperlinks for generated operation…

… names. see #786 Signed-off-by: Stéphane Galland <galland@arakhne.org>
sarl · Oct 23, 2017 · 9d2eb6a · 9d2eb6a
1 parent f5e0d65
commit 9d2eb6a
Show file tree

Hide file tree

Showing 5 changed files with 134 additions and 5 deletions.
diff --git a/...rnalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/GenerateMojo.java b/...rnalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/GenerateMojo.java
@@ -107,6 +107,13 @@ public class GenerateMojo extends AbstractDocumentationMojo {
 	@Parameter(defaultValue = "false", required = false)
 	protected boolean addYamlHeader;
 
+	/**
+	 * Indicates if an hyperlink to the operation documentation should be
+	 * added to each generated operation name.
+	 */
+	@Parameter(defaultValue = "true", required = false)
+	protected boolean addLinkToOperationName;
+
 	@Override
 	protected String getSkippingMessage() {
 		return null;
@@ -118,6 +125,7 @@ protected AbstractMarkerLanguageParser createLanguageParser(File inputFile) thro
 		if (parser instanceof MarkdownParser) {
 			final MarkdownParser mdParser = (MarkdownParser) parser;
 			mdParser.setAutoSectionNumbering(this.autoSectionNumbering);
+			mdParser.setAddLinkToOperationName(this.addLinkToOperationName);
 			mdParser.setOutlineDepthRange(AbstractMarkerLanguageParser.parseRange(this.outlineDepth, 1));
 			mdParser.setMarkdownToHtmlReferenceTransformation(this.md2html);
 			mdParser.setPureHtmlReferenceTransformation(this.transformPureHtmlLinks);

diff --git a/...o.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java b/...o.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java
@@ -23,6 +23,7 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.lang.reflect.Method;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.text.MessageFormat;
@@ -36,6 +37,7 @@
 import java.util.Set;
 import java.util.TreeMap;
 import java.util.TreeSet;
+import java.util.function.Function;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -68,6 +70,7 @@
 import io.sarl.maven.docs.parser.DynamicValidationContext;
 import io.sarl.maven.docs.parser.SarlDocumentationParser;
 import io.sarl.maven.docs.parser.SectionNumber;
+import io.sarl.maven.docs.testing.ReflectExtensions;
 
 /** Markdown parser.
  *
@@ -95,6 +98,11 @@ public class MarkdownParser extends AbstractMarkerLanguageParser {
 	 */
 	public static final boolean DEFAULT_SECTION_NUMBERING = true;
 
+	/** Indicates if a hyperlinks to the operation should be created for each operation name,
+	 * that is generated.
+	 */
+	public static final boolean DEFAULT_ADD_LINK_TO_OPERATION_NAME = true;
+
 	/** Indicates the default name of the style for the outline.
 	 */
 	public static final String DEFAULT_OUTLINE_STYLE_ID = "page_outline"; //$NON-NLS-1$
@@ -122,6 +130,8 @@ public class MarkdownParser extends AbstractMarkerLanguageParser {
 
 	private IntegerRange outlineDepthRange = new IntegerRange(DEFAULT_OUTLINE_TOP_LEVEL, DEFAULT_OUTLINE_TOP_LEVEL);
 
+	private boolean addLinkToOperationName = DEFAULT_ADD_LINK_TO_OPERATION_NAME;
+
 	private boolean sectionNumbering = DEFAULT_SECTION_NUMBERING;
 
 	private String sectionTitleFormat = DEFAULT_SECTION_TITLE_FORMAT;
@@ -439,6 +449,51 @@ public boolean isAutoSectionNumbering() {
 		return this.sectionNumbering;
 	}
 
+	/** Chagne the flag for the creation of a hyperlink to the operation documentation
+	 * to each generated operation name.
+	 *
+	 * @param enable {@code true} if the hyperlink is created.
+	 */
+	public void setAddLinkToOperationName(boolean enable) {
+		this.addLinkToOperationName = enable;
+	}
+
+	/** Replies if a hyperlink to the operation documentation should be added to each generated operation name.
+	 *
+	 * @return {@code true} if the hyperlink is created.
+	 */
+	public boolean isAddLinkToOperationName() {
+		return this.addLinkToOperationName;
+	}
+
+	/** Replies the hyperlink to the given operation.
+	 *
+	 * @param method the method.
+	 * @return the link, or {@code null} if not found.
+	 */
+	@SuppressWarnings("static-method")
+	protected URL findOperationLink(Method method) {
+		return null;
+	}
+
+	@Override
+	protected void preProcessingTransformation(CharSequence content, File inputFile, boolean validationOfInternalLinks) {
+		Function<Method, String> formatter = null;
+		if (isAddLinkToOperationName()) {
+			formatter = (it) -> {
+				final URL url = findOperationLink(it);
+				if (url != null) {
+					final StringBuilder name = new StringBuilder();
+					name.append("[").append(it.getName()).append("]("); //$NON-NLS-1$//$NON-NLS-2$
+					name.append(url.toExternalForm()).append(")"); //$NON-NLS-1$
+					return name.toString();
+				}
+				return it.getName();
+			};
+		}
+		ReflectExtensions.setDefaultNameFormatter(formatter);
+	}
+
 	@Override
 	protected String postProcessingTransformation(String content, boolean validationOfInternalLinks) {
 		String result = updateOutline(content);

diff --git a/....docs.generator/src/main/java/io/sarl/maven/docs/parser/AbstractMarkerLanguageParser.java b/....docs.generator/src/main/java/io/sarl/maven/docs/parser/AbstractMarkerLanguageParser.java
@@ -211,6 +211,7 @@ public final String transform(CharSequence content, File inputFile) {
 	 * @return the raw file content.
 	 */
 	public String transform(File inputFile, boolean validationOfInternalLinks) {
+		preProcessingTransformation(null, inputFile, validationOfInternalLinks);
 		final String rawContent = getDocumentParser().transform(inputFile);
 		return postProcessingTransformation(rawContent, validationOfInternalLinks);
 	}
@@ -223,6 +224,7 @@ public String transform(File inputFile, boolean validationOfInternalLinks) {
 	 * @return the raw file content.
 	 */
 	public String transform(Reader reader, File inputFile, boolean validationOfInternalLinks) {
+		preProcessingTransformation(null, inputFile, validationOfInternalLinks);
 		final String rawContent = getDocumentParser().transform(reader, inputFile);
 		return postProcessingTransformation(rawContent, validationOfInternalLinks);
 	}
@@ -232,13 +234,24 @@ public String transform(Reader reader, File inputFile, boolean validationOfInter
 	 * @param content the content to parse.
 	 * @param inputFile the name of the input file for locating included features and formatting error messages.
 	 * @param validationOfInternalLinks indicates if the internal links should be validated.
-	 * @return the raw file content.
+	 * @return the file content.
 	 */
 	public String transform(CharSequence content, File inputFile, boolean validationOfInternalLinks) {
+		preProcessingTransformation(content, inputFile, validationOfInternalLinks);
 		final String rawContent = getDocumentParser().transform(content, inputFile);
 		return postProcessingTransformation(rawContent, validationOfInternalLinks);
 	}
 
+	/** Pre processing of a transformation.
+	 *
+	 * @param content the preloaded content.
+	 * @param inputFile the name of the input file for locating included features and formatting error messages.
+	 * @param validationOfInternalLinks indicates if the internal links should be validated.
+	 */
+	protected void preProcessingTransformation(CharSequence content, File inputFile, boolean validationOfInternalLinks) {
+		//
+	}
+
 	/** Post processing of the content for a transformation.
 	 *
 	 * @param content the extracted content.

diff --git a/...maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java b/...maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java
@@ -188,6 +188,13 @@ public void setLineContinuation(String lineContinuationText) {
 	 */
 	public static Function2<String, String, String> getFencedCodeBlockFormatter() {
 		return (languageName, content) -> {
+			/*final StringBuilder result = new StringBuilder();
+			result.append("<div class=\\\"highlight"); //$NON-NLS-1$
+			if (!Strings.isNullOrEmpty(languageName)) {
+				result.append(" highlight-").append(languageName); //$NON-NLS-1$
+			}
+			result.append("\"><pre>\n").append(content).append("</pre></div>\n"); //$NON-NLS-1$ //$NON-NLS-2$
+			return result.toString();*/
 			return "```" + Strings.nullToEmpty(languageName).toLowerCase() + "\n" //$NON-NLS-1$ //$NON-NLS-2$
 					+ content
 					+ "```\n"; //$NON-NLS-1$

diff --git a/...o.sarl.maven.docs.testing/src/main/java/io/sarl/maven/docs/testing/ReflectExtensions.java b/...o.sarl.maven.docs.testing/src/main/java/io/sarl/maven/docs/testing/ReflectExtensions.java
@@ -33,11 +33,13 @@
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Objects;
+import java.util.function.Function;
 
 import com.google.common.collect.Iterables;
 import org.eclipse.jdt.core.Flags;
 import org.eclipse.xtext.util.Strings;
 import org.eclipse.xtext.xbase.lib.Functions;
+import org.eclipse.xtext.xbase.lib.Inline;
 import org.eclipse.xtext.xbase.lib.IterableExtensions;
 import org.eclipse.xtext.xbase.lib.Procedures;
 import org.eclipse.xtext.xbase.lib.Pure;
@@ -57,10 +59,28 @@
  */
 public final class ReflectExtensions {
 
+	private static Function<Method, String> defaultNameFormatter;
+
 	private ReflectExtensions() {
 		//
 	}
+
+	/** Change the default name formatter.
+	 *
+	 * @param formatter the default name formatter.
+	 */
+	public static void setDefaultNameFormatter(Function<Method, String> formatter) {
+		defaultNameFormatter = formatter;
+	}
 
+	/** Replies the default name formatter.
+	 *
+	 * @return the default name formatter.
+	 */
+	public static Function<Method, String> getDefaultNameFormatter() {
+		return defaultNameFormatter;
+	}
+
 	private static boolean isDeprecated(Method method) {
 		return Flags.isDeprecated(method.getModifiers()) || method.getAnnotation(Deprecated.class) != null;
 	}
@@ -72,9 +92,22 @@ private static boolean isDeprecated(Method method) {
 	 * @return the code.
 	 */
 	@Pure
+	@Inline(value = "getPublicMethodsWithFormat($1, null, $2)", imported = ReflectExtensions.class)
 	public static String getPublicMethods(Class<?> type, Class<?>... otherTypes) {
+		return getPublicMethodsWithFormat(type, null);
+	}
+
+	/** Extract the public methods from the given types.
+	 *
+	 * @param type the first type to parse.
+	 * @param nameFormatter the formatter for the function's names. If {@code null}, no formatting is applied.
+	 * @param otherTypes the other types to parse.
+	 * @return the code.
+	 */
+	@Pure
+	public static String getPublicMethodsWithFormat(Class<?> type, Function<Method, String> nameFormatter, Class<?>... otherTypes) {
 		final StringBuilder it = new StringBuilder();
-		appendPublicMethods(it, false, IterableExtensions.flatten(
+		appendPublicMethods(it, false, nameFormatter, IterableExtensions.flatten(
 				Arrays.asList(
 						Collections.singletonList(type),
 						Arrays.asList(otherTypes))));
@@ -87,17 +120,20 @@ public static String getPublicMethods(Class<?> type, Class<?>... otherTypes) {
 	 * @param indent indicates if the code should be indented.
 	 * @param types the types to parse.
 	 */
+	@Inline(value = "appendPublicMethods($1, $2, null, $4.asList($3))", imported = Arrays.class)
 	public static void appendPublicMethods(StringBuilder it, boolean indent, Class<?>... types) {
-		appendPublicMethods(it, indent, Arrays.asList(types));
+		appendPublicMethods(it, indent, null, Arrays.asList(types));
 	}
 
 	/** Extract the public methods from the given types.
 	 *
 	 * @param it the output.
 	 * @param indent indicates if the code should be indented.
+	 * @param nameFormatter the formatter for the function's names. If {@code null}, no formatting is applied.
 	 * @param types the types to parse.
 	 */
-	public static void appendPublicMethods(StringBuilder it, boolean indent, Iterable<? extends Class<?>> types) {
+	public static void appendPublicMethods(StringBuilder it, boolean indent, Function<Method, String> nameFormatter, 
+			Iterable<? extends Class<?>> types) {
 		final List<String> lines = new LinkedList<>();
 		for (final Class<?> type : types) {
 			for (final Method method : type.getDeclaredMethods()) {
@@ -108,7 +144,17 @@ public static void appendPublicMethods(StringBuilder it, boolean indent, Iterabl
 					if (indent) {
 						line.append("\t"); //$NON-NLS-1$
 					}
-					line.append("def ").append(method.getName()); //$NON-NLS-1$
+					Function<Method, String> nformatter = nameFormatter;
+					if (nformatter == null) {
+						nformatter = getDefaultNameFormatter();
+					}
+					final String formattedName;
+					if (nformatter != null) {
+						formattedName = nformatter.apply(method);
+					} else {
+						formattedName = method.getName();
+					}
+					line.append("def ").append(formattedName); //$NON-NLS-1$
 					if (method.getParameterCount() > 0) {
 						line.append("("); //$NON-NLS-1$
 						boolean first = true;