diff --git a/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/GenerateMojo.java b/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/GenerateMojo.java index 2a76f20a5c..c79d4e7eb4 100644 --- a/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/GenerateMojo.java +++ b/main/externalmaven/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/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java b/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java index 548984c284..b5f665628c 100644 --- a/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/markdown/MarkdownParser.java +++ b/main/externalmaven/io.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 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/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/AbstractMarkerLanguageParser.java b/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/AbstractMarkerLanguageParser.java index 3058f363cc..82c08098e0 100644 --- a/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/AbstractMarkerLanguageParser.java +++ b/main/externalmaven/io.sarl.maven.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/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java b/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java index c59cf42c96..214865dc16 100644 --- a/main/externalmaven/io.sarl.maven.docs.generator/src/main/java/io/sarl/maven/docs/parser/SarlDocumentationParser.java +++ b/main/externalmaven/io.sarl.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 getFencedCodeBlockFormatter() { return (languageName, content) -> { + /*final StringBuilder result = new StringBuilder(); + result.append("
\n").append(content).append("
\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/main/externalmaven/io.sarl.maven.docs.testing/src/main/java/io/sarl/maven/docs/testing/ReflectExtensions.java b/main/externalmaven/io.sarl.maven.docs.testing/src/main/java/io/sarl/maven/docs/testing/ReflectExtensions.java index a7146e1353..4a0ca7c9ed 100644 --- a/main/externalmaven/io.sarl.maven.docs.testing/src/main/java/io/sarl/maven/docs/testing/ReflectExtensions.java +++ b/main/externalmaven/io.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 defaultNameFormatter; + private ReflectExtensions() { // } + + /** Change the default name formatter. + * + * @param formatter the default name formatter. + */ + public static void setDefaultNameFormatter(Function formatter) { + defaultNameFormatter = formatter; + } + /** Replies the default name formatter. + * + * @return the default name formatter. + */ + public static Function 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 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> types) { + public static void appendPublicMethods(StringBuilder it, boolean indent, Function nameFormatter, + Iterable> types) { final List 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 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;