Community
Participate
Working Groups
A specifier who provides services for AQL should be able to contribute a documentation for those services. This documentation should be contributed with annotations on those services with a minimal amount of dependencies.
To illustrate how we could proceed, I will take the example of the method concat. The keywords of the Java language (throw, throws, return, etc) cannot be used as a field on an annotation. /** * Returns a string that is the result of a concatenation of a string "b" at the end of a self string * "self". * * @param self * the "self" string from which we concatenate the string "b". * @param b * the string that will be concatenated to the string "self". * @return The concatenated String. */ public String concat(String self, String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } If we want to document the parameters of an operations we will need multiple occurrences of an annotation @Param. Those occurrences can be on the method or on each parameter. @Param(name = "self", value = "The \"self\" string from which we concatenate the string \"b\".") @Param(name = "b", value = "the string that will be concatenated to the string \"self\".") public String concat(String self, String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } or public String concat( @Param(name = "self", value = "The \"self\" string from which we concatenate the string \"b\".") String self, @Param(name = "b", value = "the string that will be concatenated to the string \"self\".")String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } Given the fact that we have to write some sizable content in those annotation, using them on the type directly would reduce the readability of the code. Given the fact that we have not access to repeating annotations (Java 8 only), those annotations will have to be encapsulated in another annotation which can also contain the documentation of the method. @Documentation ( value = "Returns a string that is the result of a concatenation of a string \"b\" at the end of a self string \"self\".", params = { @Param(name = "self", value = "The \"self\" string from which we concatenate the string \"b\"."), @Param(name = "b", value = "the string that will be concatenated to the string \"self\".") } ) public String concat(String self, String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } If we have to encapsulate the parameters annotation, we should encapsulate the annotation for the return type too. We cannot use a type annotation for the return type (Java 8) and using it would dramatically reduce the readability of the code. @Documentation ( value = "Returns a string that is the result of a concatenation of a string \"b\" at the end of a self string \"self\".", params = { @Param(name = "self", value = "The \"self\" string from which we concatenate the string \"b\"."), @Param(name = "b", value = "the string that will be concatenated to the string \"self\".") }, result = "The concatenated String." ) public String concat(String self, String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } If the operation can throw an exception, it can also be documented thanks to a dedicated annotation. Since an operation can throw multiple kind of exceptions, we are facing the same issue as with parameters. The method concat used in this example does not throw any exception so this example is not real. @Documentation ( value = "Returns a string that is the result of a concatenation of a string \"b\" at the end of a self string \"self\".", params = { @Param(name = "self", value = "The \"self\" string from which we concatenate the string \"b\"."), @Param(name = "b", value = "the string that will be concatenated to the string \"self\".") }, result = "The concatenated String.", exceptions = { @Throw(type = IllegalArgumentException.class, value = "This exception will be thrown if we need to...") } ) public String concat(String self, String b) { return Strings.nullToEmpty(self) + Strings.nullToEmpty(b); } Using those annotations, we could provide all the necessary information regarding our service and we could easily retrieve those information at runtime.
New Gerrit change created: https://git.eclipse.org/r/52624 WARNING: this patchset contains 1881 new lines of code and may require a Contribution Questionnaire (CQ) if the author is not a committer on the project. Please see:https://wiki.eclipse.org/Project_Management_Infrastructure/Creating_A_Contribution_Questionnaire
Created attachment 255477 [details] Result of the documentation in the Sirius content assist mechanism This screenshot shows the result in Sirius with the documentation provided by the annotations in the documentation of the field content assist proposal in Sirius. An issue may appear in Sirius since they are using the field content assist system and not the text content assist system which provides the ability to customize heavily the completion proposals (contrary to the content proposals used by Sirius). As a result, support for HTML in the documentation and other advanced features is not possible.
In order to provide an up to date version of the user guide with all the operations available for the end users, several options are available: 1 - Maven We could create a maven plugin, used during the build of Acceleo, in order to generate a document with the description of all the standard services. This document could then be used by the Acceleo documentation and retrieved if we want to publish it to a website. This plugin could also be used by a specifier if she/he want to document its own services. The major drawback of this solution is a technical one since it will be quite complex to develop a maven plugin for this task. In order to use the JDT to parse the Java source code, we would have to use it as a dependency in a maven context while it has not really been created for that. 2 - Builder We could instead use an Eclipse builder, applied on the projects containing Java services like org.eclipse.acceleo.query in order to generate a HTML documentation while the code is modified. In a similar fashion as the baseliner, the documentation would be contributed on the Git repository of Acceleo and it could be maintained easily. This documentation could be available for the documentation plugin and it could also be published on the Acceleo website during the build. The major drawback of this solution is the fact that we will have a plugin in Acceleo which will have to be installed in order to develop Acceleo itself. 3 - Computed documentation It seems possible using the extension point org.eclipse.help.contentExtension to provide programmatically computed help to Eclipse. This mechanism would be used in order to provide a help page using the information of the various plugins contributing services. While it could be useful to see the services of additional plugins, it may be more difficult to retrieve the documentation page to export it on a simple website.
I will start by implementing the computed html pages for the documentation since it is pretty straightforward and it will e transparent for the other contributors of the Acceleo project.
Created attachment 255616 [details] Result in the embedded documentation The AQL documentation will be computed directly from the service providers themselves.
New Gerrit change created: https://git.eclipse.org/r/53162
Gerrit change https://git.eclipse.org/r/52624 was merged to [master]. Commit: http://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/commit/?id=cd308d2077a15cd198e62c56e9f78b8fb8cbcbb6
Gerrit change https://git.eclipse.org/r/53162 was merged to [master]. Commit: http://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/commit/?id=6e7dc74e1ce51fc294a94420b03d3426be45387f
This improvement is available on master
Closing as per comment #10
