diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.xtend index e7a4fff28..0a232c7db 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.xtend @@ -10,6 +10,12 @@ package org.eclipse.xtext.xtext.generator import org.eclipse.xtext.xtext.generator.AbstractStubGeneratingFragment import org.eclipse.xtend.lib.annotations.Accessors +/** + * A fragment that generates a class that inherits from the generated class of the super-grammar. + * This inheritance can be disabled with the {@code inheritImplementation} property. + */ abstract class AbstractInheritingFragment extends AbstractStubGeneratingFragment { + @Accessors boolean inheritImplementation = true + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.xtend index d51879812..f738452cb 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.xtend @@ -11,6 +11,14 @@ import com.google.inject.Inject import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.xtext.generator.util.BooleanGeneratorOption +/** + * A fragment that generates a stub, that is a class where the user can add + * custom behavior, e.g. validation or formatting rules. The stub is generated into + * the source folder that is not overwritten when the generator is executed again + * ({@code src} for plain project layout, {@code src/main/java} for Maven/Gradle + * project layout). If you want the stub to be generated again, delete the already + * existing file. + */ abstract class AbstractStubGeneratingFragment extends AbstractXtextGeneratorFragment { @Inject diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.xtend index 641f624a7..6f6fbafbe 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.xtend @@ -13,6 +13,10 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.Grammar import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig +/** + * Convenience class for implementing generator fragments. Provides access to the + * {@link IXtextProjectConfig project configuration} and the {@link IXtextGeneratorLanguage language configuration}. + */ abstract class AbstractXtextGeneratorFragment implements IXtextGeneratorFragment { @Accessors(PROTECTED_GETTER) diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/CodeConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/CodeConfig.xtend index b2d079e66..e178f944e 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/CodeConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/CodeConfig.xtend @@ -19,7 +19,6 @@ import java.nio.charset.Charset /** * Configuration object for generated code. - * @noextend */ class CodeConfig implements IGuiceAwareGeneratorComponent { @@ -56,7 +55,7 @@ class CodeConfig implements IGuiceAwareGeneratorComponent { *
${date}
- the current date (month day, year)${year}
- the current year${user}
- the content of the 'user.name' system property${version}
- the generator plug-in version${version}
- the generator bundle version+ * class MyGeneratorModule extends DefaultGeneratorModule { + * def Class<? extends XtextGeneratorNaming> bindXtextGeneratorNaming() { + * MyGeneratorNaming + * } + * } + **/ class DefaultGeneratorModule extends AbstractGenericModule { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.xtend index 41cb99a04..b0c25f3a8 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.xtend @@ -10,7 +10,9 @@ package org.eclipse.xtext.xtext.generator import com.google.inject.Injector /** - * @noreference + * The Xtext generator uses dependency injection with Guice + * for distributing the configuration to all its components. Instances of this interface can initialize + * themselves with a Guice injector, e.g. by calling {@code injector.injectMembers(this)}. */ interface IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.xtend index 61be2318d..32b6a2a40 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.xtend @@ -8,8 +8,8 @@ package org.eclipse.xtext.xtext.generator /** - * A fragment that contributes to the {@link XtextGenerator}. - * @noimplement + * A fragment that contributes to the {@link XtextGenerator}. Use {@link AbstractXtextGeneratorFragment} + * for implementing new fragments. */ interface IXtextGeneratorFragment extends IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.xtend index 93e03d43b..ec3f0d199 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.xtend @@ -14,7 +14,9 @@ import org.eclipse.xtext.xtext.generator.model.GuiceModuleAccess import org.eclipse.xtext.xtext.generator.model.StandaloneSetupAccess /** - * @noimplement + * Configuration for an Xtext language. Implemented by {@link XtextGeneratorLanguage}. + * + * @noimplement This interface should not be implemented by clients. */ interface IXtextGeneratorLanguage { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/ImplicitFragment.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/ImplicitFragment.xtend index 87ad52374..5e209455b 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/ImplicitFragment.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/ImplicitFragment.xtend @@ -17,6 +17,9 @@ import org.eclipse.xtext.xtext.generator.xbase.XbaseUsageDetector import static extension org.eclipse.xtext.GrammarUtil.* import static extension org.eclipse.xtext.xtext.generator.model.TypeReference.* +/** + * The ImplicitFragment is added in the first slot to all language configurations. + */ package class ImplicitFragment extends AbstractStubGeneratingFragment { @Inject extension XbaseUsageDetector diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/Issues.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/Issues.xtend index 68d7e2618..d1344d762 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/Issues.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/Issues.xtend @@ -8,11 +8,16 @@ package org.eclipse.xtext.xtext.generator /** - * @noreference + * Use this to report configuration problems during the {@link IXtextGeneratorFragment#checkConfiguration(Issues)} phase. */ interface Issues { + def void addError(String message) + def void addError(String message, Object source) + def void addWarning(String message) + def void addWarning(String message, Object source) + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/LanguageModule.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/LanguageModule.xtend index 74905fcfa..a5eb6a598 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/LanguageModule.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/LanguageModule.xtend @@ -13,6 +13,10 @@ import org.eclipse.xtext.Grammar import org.eclipse.xtext.service.AbstractGenericModule import org.eclipse.xtext.xtext.RuleNames +/** + * Language-specific Guice module that is used in a child injector of the global injector + * derived from {@link DefaultGeneratorModule}. + */ @FinalFieldsConstructor package class LanguageModule extends AbstractGenericModule { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/MweIssues.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/MweIssues.xtend index 1abcf7303..ab38460e6 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/MweIssues.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/MweIssues.xtend @@ -11,7 +11,7 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtend.lib.annotations.FinalFieldsConstructor /** - * @noreference + * {@link Issues} implementation for MWE2 workflows. */ @FinalFieldsConstructor class MweIssues implements Issues { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/StandardLanguage.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/StandardLanguage.xtend index 243f08561..cfb0de5ff 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/StandardLanguage.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/StandardLanguage.xtend @@ -40,8 +40,24 @@ import org.eclipse.xtext.xtext.generator.xbase.XbaseGeneratorFragment2 import org.eclipse.xtext.xtext.generator.xbase.XtypeGeneratorFragment2 /** + * This specialization of the {@link XtextGeneratorLanguage} adds all the standard generator fragments + * that are commonly used for Xtext languages. This eliminates the need to list all these fragments + * explicitly in the workflow file. More fragments can be added as required, but the standard fragments + * cannot be removed. However, most of these fragments disable themselves automatically if they are + * not applicable, e.g. the {@link WebIntegrationFragment} does not generate anything if the web project + * is disabled in the project configuration. + * + *
The configuration for individual fragments can be made with the corresponding properties. + * For example, write + *
+ * formatter = formatting.Formatter2Fragment2 { + * generateStub = true + * } + *+ * to enable stub generation for the formatter. + * * @author Sven Efftinge - Initial contribution and API - * @noextend + * @noextend This class should not be extended by clients. */ @Accessors(PUBLIC_SETTER, PROTECTED_GETTER) @Log class StandardLanguage extends XtextGeneratorLanguage { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.xtend index e8a372aac..a33ba55b1 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.xtend @@ -16,13 +16,18 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig /** - * @noextend + * This component cleans all directories for generated code according to the project configuration + * (usually 'src-gen' for plain layout and 'src/main/xtext-gen' for Maven/Gradle layout). + * + * @noextend This class should not be extended by clients. */ class XtextDirectoryCleaner implements IGuiceAwareGeneratorComponent { + @Inject IXtextProjectConfig config @Accessors(PUBLIC_SETTER) boolean enabled = true + @Accessors(PUBLIC_SETTER) boolean useDefaultExcludes = true diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGenerator.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGenerator.xtend index e7aa39f03..4774089bc 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGenerator.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGenerator.xtend @@ -40,10 +40,28 @@ import org.eclipse.xtext.xtext.generator.model.project.BundleProjectConfig import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig /** - * The Xtext language infrastructure generator. Can be configured with {@link IXtextGeneratorFragment} - * instances as well as with some properties declared via setter or adder methods. + * The Xtext language infrastructure generator. Use the {@code configuration} block to add general + * configuration for your Xtext project and the generated code, e.g. + *
+ * configuration = { + * project = model.project.StandardProjectConfig { + * baseName = "org.example.language" + * rootPath = ".." + * } + * code = { + * encoding = 'ISO-8859-1' + * } + * } + *+ * You can generate code for one or more Xtext languages within the same project. For each language, + * add a {@code language} block, e.g. + *
+ * language = StandardLanguage { + * name = "org.example.language.MyExampleLanguage" + * } + ** - * @noextend + * @noextend This class should not be extended by clients. */ @Log class XtextGenerator extends AbstractWorkflowComponent2 { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.xtend index 3a62019d3..a240988f8 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.xtend @@ -40,7 +40,19 @@ import org.eclipse.xtext.xtext.generator.model.StandaloneSetupAccess import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig /** - * @noextend + * Configuration for an Xtext language. Use this class if you need to specify exactly which generator + * fragments you want to include, or alternatively {@link StandardLanguage} to work with the standard + * fragments. + * + *
The most important property is {@code name}, which should be set to the language name exactly + * as specified in the grammar file. If the default grammar resolution based on the name does not + * work in your particular scenario, set the {@code grammarUri} property instead. Furthermore, + * use {@code fileExtensions} to specify the file extensions for your language.
+ * + *Generator fragments can be added with the {@code fragment} property. See {@link StandardLanguage} + * for a list of useful fragments.
+ * + * @noextend This class should not be extended by clients. */ @Log class XtextGeneratorLanguage extends CompositeGeneratorFragment2 implements IXtextGeneratorLanguage { @@ -95,6 +107,10 @@ class XtextGeneratorLanguage extends CompositeGeneratorFragment2 implements IXte @Inject XtextGeneratorResourceSetInitializer resourceSetInitializer + /** + * The URI of the grammar file. Use this property if the automatic grammar resolution based on {@link #setName(String)} + * does not work in your particular scenario. + */ def void setGrammarUri(String uri) { this.grammarUri = uri } @@ -103,14 +119,25 @@ class XtextGeneratorLanguage extends CompositeGeneratorFragment2 implements IXte grammarUri ?: new File(projectConfig.runtime.src.path, name.replace('.', '/') + ".xtext").toURI.toString } + /** + * The language name exactly as specified in the grammar. + */ def void setName(String name) { this.name = name } + /** + * Either a single file extension or a comma-separated list of extensions for which the language + * shall be registered. + */ def void setFileExtensions(String fileExtensions) { this.fileExtensions = fileExtensions.trim.split('\\s*,\\s*').toList } + /** + * Add a resource to be included in the resource set that will be used to load the grammar file. + * This is often necessary if additional Ecore models are referenced by the grammar. + */ def void addReferencedResource(String referencedResource) { this.referencedResources += referencedResource } diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorNaming.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorNaming.xtend index 2ede13a10..1fa618ba5 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorNaming.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorNaming.xtend @@ -15,7 +15,8 @@ import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig import static org.eclipse.xtext.GrammarUtil.* /** - * @noreference + * Configuration of the names of the generated classes. Create a subclass and register it with a specialized + * {@link DefaultGeneratorModule} in order to customize some class or package names. */ class XtextGeneratorNaming { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorResourceSetInitializer.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorResourceSetInitializer.xtend index f289d1739..55ddc9230 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorResourceSetInitializer.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorResourceSetInitializer.xtend @@ -21,8 +21,8 @@ import org.eclipse.xtext.util.internal.Log import org.eclipse.emf.ecore.EcorePackage /** - * @noextend - * @noreference + * Initializes a resource set in order to load the grammar of a language. The resources to include are specified + * via {@link XtextGeneratorLanguage#addReferencedResource(String)}. */ @Log class XtextGeneratorResourceSetInitializer { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorStandaloneSetup.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorStandaloneSetup.xtend index f4ae0c658..9839d2a84 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorStandaloneSetup.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorStandaloneSetup.xtend @@ -16,17 +16,19 @@ import org.eclipse.xtext.util.internal.Log import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig /** - * @noextend + * Standalone setup for resolving EMF URIs in the context of the {@link XtextGenerator}. The actual + * setup is done by {@link StandaloneSetup}. */ @Log class XtextGeneratorStandaloneSetup implements IGuiceAwareGeneratorComponent { + @Inject IXtextProjectConfig projectConfig @Accessors boolean scanClasspath = true override initialize(Injector injector) { injector.injectMembers(this) - setup + setup() } private def void setup() { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorTemplates.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorTemplates.xtend index 8315d0fb5..4ce79c739 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorTemplates.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/XtextGeneratorTemplates.xtend @@ -38,7 +38,7 @@ import org.eclipse.xtext.xtext.generator.model.annotations.SuppressWarningsAnnot import static extension org.eclipse.xtext.xtext.generator.model.TypeReference.* /** - * @noreference + * Templates for generating the common language infrastructure. */ @Singleton class XtextGeneratorTemplates { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/FileAccessFactory.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/FileAccessFactory.xtend index 67ec6e8ca..71005d8e4 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/FileAccessFactory.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/FileAccessFactory.xtend @@ -11,6 +11,9 @@ import com.google.inject.Inject import org.eclipse.xtext.xtext.generator.CodeConfig import org.eclipse.xtend2.lib.StringConcatenationClient +/** + * Factory for creating text files, Java files, and Xtend files. + */ class FileAccessFactory { @Inject CodeConfig codeConfig diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GeneratedJavaFileAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GeneratedJavaFileAccess.xtend index 8106632d5..4c3f096fc 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GeneratedJavaFileAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GeneratedJavaFileAccess.xtend @@ -7,6 +7,9 @@ import org.eclipse.xtext.xtext.generator.CodeConfig import org.eclipse.xtext.xtext.generator.model.JavaFileAccess.JavaTypeAwareStringConcatenation import org.eclipse.xtext.xtext.generator.model.annotations.IClassAnnotation +/** + * A specialized Java file generator used for classes in the 'src-gen' folder. + */ class GeneratedJavaFileAccess extends JavaFileAccess { CharSequence typeComment diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GuiceModuleAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GuiceModuleAccess.xtend index e0659f98a..edc12d69f 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GuiceModuleAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/GuiceModuleAccess.xtend @@ -15,6 +15,9 @@ import org.eclipse.xtend.lib.annotations.Data import org.eclipse.xtend2.lib.StringConcatenationClient import org.eclipse.xtext.util.internal.Log +/** + * Configuration object for Guice modules based on {@link org.eclipse.xtext.service.AbstractGenericModule}. + */ @Log class GuiceModuleAccess { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/IXtextGeneratorFileSystemAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/IXtextGeneratorFileSystemAccess.xtend index 7a473a46e..9ee22047d 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/IXtextGeneratorFileSystemAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/IXtextGeneratorFileSystemAccess.xtend @@ -7,9 +7,14 @@ *******************************************************************************/ package org.eclipse.xtext.xtext.generator.model +import com.google.inject.ImplementedBy import org.eclipse.xtext.generator.IFileSystemAccess2 import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent +/** + * File system access for the Xtext generator. + */ +@ImplementedBy(XtextGeneratorFileSystemAccess) interface IXtextGeneratorFileSystemAccess extends IFileSystemAccess2, IGuiceAwareGeneratorComponent { def String getPath() diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/JavaFileAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/JavaFileAccess.xtend index 92a20f93b..2515c87b7 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/JavaFileAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/JavaFileAccess.xtend @@ -17,6 +17,9 @@ import org.eclipse.xtend2.lib.StringConcatenationClient import org.eclipse.xtext.util.internal.CodeGenUtil2 import org.eclipse.xtext.xtext.generator.CodeConfig +/** + * A utility class for generating Java files. + */ class JavaFileAccess extends TextFileAccess { /** diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/ManifestAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/ManifestAccess.xtend index ddc08c72c..a1914f679 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/ManifestAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/ManifestAccess.xtend @@ -19,6 +19,9 @@ import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent import com.google.inject.Injector import org.eclipse.xtext.util.Strings +/** + * Configuration object for MANIFEST.MF files for use in Eclipse. + */ @Log @Accessors class ManifestAccess extends TextFileAccess implements IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/PluginXmlAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/PluginXmlAccess.xtend index eeb20a46a..a4c65fac5 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/PluginXmlAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/PluginXmlAccess.xtend @@ -17,6 +17,9 @@ import com.google.inject.Inject import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent import com.google.inject.Injector +/** + * Configuration object for plugin.xml files for use in Eclipse. + */ @Log @Accessors class PluginXmlAccess extends TextFileAccess implements IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/StandaloneSetupAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/StandaloneSetupAccess.xtend index a97d0ec0a..89db31b88 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/StandaloneSetupAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/StandaloneSetupAccess.xtend @@ -12,6 +12,10 @@ import java.util.Set import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtend2.lib.StringConcatenationClient +/** + * Configuration object for the generated standalone setup class. This class is responsible for adding + * required EMF packages to the global registries. + */ @Accessors class StandaloneSetupAccess { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TextFileAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TextFileAccess.xtend index f2f52bfca..8a327556b 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TextFileAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TextFileAccess.xtend @@ -12,6 +12,9 @@ import org.eclipse.xtext.generator.IFileSystemAccess2 import org.eclipse.xtend2.lib.StringConcatenationClient import org.eclipse.xtend2.lib.StringConcatenation +/** + * A utility class for generating plain text files. + */ class TextFileAccess { @Accessors diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TypeReference.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TypeReference.xtend index 47ffcf0a6..7e8ef718d 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TypeReference.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/TypeReference.xtend @@ -18,6 +18,10 @@ import org.eclipse.xtend.lib.annotations.EqualsHashCode import org.eclipse.xtext.xtext.generator.IXtextGeneratorLanguage import org.eclipse.xtext.xtext.generator.util.GenModelUtil2 +/** + * Reference to a Java type. Use this for automatic import of types in {@link JavaFileAccess} + * and {@link XtendFileAccess}. + */ @Accessors @EqualsHashCode class TypeReference { diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/XtendFileAccess.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/XtendFileAccess.xtend index 15e860305..75091fcff 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/XtendFileAccess.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/XtendFileAccess.xtend @@ -9,6 +9,9 @@ package org.eclipse.xtext.xtext.generator.model import org.eclipse.xtext.xtext.generator.CodeConfig +/** + * A utility class for generating Xtend files. + */ class XtendFileAccess extends JavaFileAccess { /** diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/BundleProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/BundleProjectConfig.xtend index c51600c59..3a1f27d51 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/BundleProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/BundleProjectConfig.xtend @@ -14,10 +14,13 @@ import org.eclipse.xtext.xtext.generator.model.ManifestAccess import org.eclipse.xtext.xtext.generator.model.PluginXmlAccess /** - * @noextend + * Configuration of subprojects that can be used as Eclipse bundles. + * + * @noextend This class should not be extended by clients. */ @Accessors -class BundleProjectConfig extends SubProjectConfig implements IBundleProjectConfig{ +class BundleProjectConfig extends SubProjectConfig implements IBundleProjectConfig { + ManifestAccess manifest PluginXmlAccess pluginXml diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IBundleProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IBundleProjectConfig.xtend index 026bc9f6c..d2493cb63 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IBundleProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IBundleProjectConfig.xtend @@ -11,9 +11,14 @@ import org.eclipse.xtext.xtext.generator.model.ManifestAccess import org.eclipse.xtext.xtext.generator.model.PluginXmlAccess /** - * @noimplement + * Configuration of subprojects that can be used as Eclipse bundles. + * + * @noimplement This interface should not be implemented by clients. */ interface IBundleProjectConfig extends ISubProjectConfig { + def ManifestAccess getManifest() + def PluginXmlAccess getPluginXml() + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IRuntimeProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IRuntimeProjectConfig.xtend index 28fe42998..ba8e26397 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IRuntimeProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IRuntimeProjectConfig.xtend @@ -10,9 +10,14 @@ package org.eclipse.xtext.xtext.generator.model.project import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noimplement + * Configuration of the runtime project, i.e. the main subproject containing the language definition. + * + * @noimplement This interface should not be implemented by clients. */ interface IRuntimeProjectConfig extends IBundleProjectConfig { + def IXtextGeneratorFileSystemAccess getEcoreModel() + def String getEcoreModelFolder() + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/ISubProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/ISubProjectConfig.xtend index 8b3d514cc..00a7f97a7 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/ISubProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/ISubProjectConfig.xtend @@ -11,13 +11,22 @@ import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noimplement + * Configuration of subprojects. + * + * @noimplement This interface should not be implemented by clients. */ interface ISubProjectConfig extends IGuiceAwareGeneratorComponent { + def boolean isEnabled() + def String getName() + def IXtextGeneratorFileSystemAccess getRoot() + def IXtextGeneratorFileSystemAccess getMetaInf() + def IXtextGeneratorFileSystemAccess getSrc() + def IXtextGeneratorFileSystemAccess getSrcGen() + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IWebProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IWebProjectConfig.xtend index 5db5030d3..066cca5f9 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IWebProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IWebProjectConfig.xtend @@ -10,8 +10,12 @@ package org.eclipse.xtext.xtext.generator.model.project import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noimplement + * Configuration of the web project. + * + * @noimplement This interface should not be implemented by clients. */ interface IWebProjectConfig extends ISubProjectConfig { + def IXtextGeneratorFileSystemAccess getAssets() + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IXtextProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IXtextProjectConfig.xtend index d71abc2af..f296d5b67 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IXtextProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/IXtextProjectConfig.xtend @@ -11,16 +11,28 @@ import java.util.List import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent /** - * @noimplement + * Configuration of the subprojects for one or more Xtext languages. Implemented by {@link XtextProjectConfig}. + * + * @noimplement This interface should not be implemented by clients. */ interface IXtextProjectConfig extends IGuiceAwareGeneratorComponent { + def IRuntimeProjectConfig getRuntime() + def IBundleProjectConfig getRuntimeTest() + def IBundleProjectConfig getGenericIde() + def IBundleProjectConfig getEclipsePlugin() + def IBundleProjectConfig getEclipsePluginTest() + def ISubProjectConfig getIdeaPlugin() + def IWebProjectConfig getWeb() + def List extends ISubProjectConfig> getEnabledProjects() + def List extends ISubProjectConfig> getTestProjects() + } \ No newline at end of file diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/RuntimeProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/RuntimeProjectConfig.xtend index ded635b9b..86f4c68dd 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/RuntimeProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/RuntimeProjectConfig.xtend @@ -13,7 +13,9 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noextend + * Configuration of the runtime project, i.e. the main subproject containing the language definition. + * + * @noextend This class should not be extended by clients. */ class RuntimeProjectConfig extends BundleProjectConfig implements IRuntimeProjectConfig { @Accessors(PUBLIC_GETTER) diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/StandardProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/StandardProjectConfig.xtend index ddb1cbcb1..9ade10cb2 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/StandardProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/StandardProjectConfig.xtend @@ -12,7 +12,10 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.xtext.generator.Issues /** - * @noextend + * Specialized project configuration that uses standard names and paths. Usually it is sufficient to + * set the {@code baseName} and {@code rootPath} properties and to enable the required subprojects. + * + * @noextend This class should not be extended by clients. */ @Accessors class StandardProjectConfig extends XtextProjectConfig { @@ -23,11 +26,17 @@ class StandardProjectConfig extends XtextProjectConfig { String rootPath String baseName + /** + * The base name of the project, which is usually equal to the runtime subproject. + */ @Mandatory def setBaseName(String baseName) { this.baseName = baseName } + /** + * The root path, usually {@code ".."}. + */ @Mandatory def setRootPath(String rootPath) { this.rootPath = rootPath diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/SubProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/SubProjectConfig.xtend index 6e0fef593..06b63fbf5 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/SubProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/SubProjectConfig.xtend @@ -14,9 +14,12 @@ import org.eclipse.xtext.xtext.generator.Issues import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noextend + * Configuration of subprojects. + * + * @noextend This class should not be extended by clients. */ class SubProjectConfig implements ISubProjectConfig { + @Inject @Accessors(PUBLIC_GETTER) XtextProjectConfig owner diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/WebProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/WebProjectConfig.xtend index 07cce2ac0..31b184885 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/WebProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/WebProjectConfig.xtend @@ -12,11 +12,15 @@ import org.eclipse.xtend.lib.annotations.Accessors import org.eclipse.xtext.xtext.generator.model.IXtextGeneratorFileSystemAccess /** - * @noextend + * Configuration of the web project. + * + * @noextend This class should not be extended by clients. */ class WebProjectConfig extends SubProjectConfig implements IWebProjectConfig { + @Accessors(PUBLIC_GETTER) String assetsPath + @Accessors(PUBLIC_GETTER) IXtextGeneratorFileSystemAccess assets diff --git a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/XtextProjectConfig.xtend b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/XtextProjectConfig.xtend index aa28f0090..a1525409a 100644 --- a/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/XtextProjectConfig.xtend +++ b/org.eclipse.xtext.xtext.generator/src/org/eclipse/xtext/xtext/generator/model/project/XtextProjectConfig.xtend @@ -18,16 +18,26 @@ import org.eclipse.xtext.xtext.generator.model.PluginXmlAccess import org.eclipse.xtext.xtext.generator.model.XtextGeneratorFileSystemAccess /** - * @noextend + * Configuration of the subprojects for one or more Xtext languages. If the standard project names + * and layout is sufficient, use {@link StandardProjectConfig}. + * + * @noextend This class should not be extended by clients. */ @Accessors class XtextProjectConfig implements IXtextProjectConfig { + RuntimeProjectConfig runtime = new RuntimeProjectConfig + BundleProjectConfig runtimeTest = new BundleProjectConfig + BundleProjectConfig genericIde = new BundleProjectConfig + BundleProjectConfig eclipsePlugin = new BundleProjectConfig + BundleProjectConfig eclipsePluginTest = new BundleProjectConfig + SubProjectConfig ideaPlugin = new SubProjectConfig + WebProjectConfig web = new WebProjectConfig @Inject CodeConfig codeConfig diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.java index c3637791f..da3ff2f4f 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractInheritingFragment.java @@ -11,6 +11,10 @@ import org.eclipse.xtend.lib.annotations.Accessors; import org.eclipse.xtext.xbase.lib.Pure; import org.eclipse.xtext.xtext.generator.AbstractStubGeneratingFragment; +/** + * A fragment that generates a class that inherits from the generated class of the super-grammar. + * This inheritance can be disabled with the {@code inheritImplementation} property. + */ @SuppressWarnings("all") public abstract class AbstractInheritingFragment extends AbstractStubGeneratingFragment { @Accessors diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.java index 6fa08661c..9b851ae77 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractStubGeneratingFragment.java @@ -16,6 +16,14 @@ import org.eclipse.xtext.xtext.generator.AbstractXtextGeneratorFragment; import org.eclipse.xtext.xtext.generator.CodeConfig; import org.eclipse.xtext.xtext.generator.util.BooleanGeneratorOption; +/** + * A fragment that generates a stub, that is a class where the user can add + * custom behavior, e.g. validation or formatting rules. The stub is generated into + * the source folder that is not overwritten when the generator is executed again + * ({@code src} for plain project layout, {@code src/main/java} for Maven/Gradle + * project layout). If you want the stub to be generated again, delete the already + * existing file. + */ @SuppressWarnings("all") public abstract class AbstractStubGeneratingFragment extends AbstractXtextGeneratorFragment { @Inject diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.java index 2add0884d..1b443ccd6 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/AbstractXtextGeneratorFragment.java @@ -18,6 +18,10 @@ import org.eclipse.xtext.xtext.generator.IXtextGeneratorLanguage; import org.eclipse.xtext.xtext.generator.Issues; import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig; +/** + * Convenience class for implementing generator fragments. Provides access to the + * {@link IXtextProjectConfig project configuration} and the {@link IXtextGeneratorLanguage language configuration}. + */ @SuppressWarnings("all") public abstract class AbstractXtextGeneratorFragment implements IXtextGeneratorFragment { @Accessors(AccessorType.PROTECTED_GETTER) diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/CodeConfig.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/CodeConfig.java index 81a5e3c85..5aa87598e 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/CodeConfig.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/CodeConfig.java @@ -24,7 +24,6 @@ import org.eclipse.xtext.xtext.generator.model.annotations.IClassAnnotation; /** * Configuration object for generated code. - * @noextend */ @SuppressWarnings("all") public class CodeConfig implements IGuiceAwareGeneratorComponent { @@ -65,7 +64,7 @@ public class CodeConfig implements IGuiceAwareGeneratorComponent { *${date}
- the current date (month day, year)${year}
- the current year${user}
- the content of the 'user.name' system property${version}
- the generator plug-in version${version}
- the generator bundle version+ * class MyGeneratorModule extends DefaultGeneratorModule { + * def Class<? extends XtextGeneratorNaming> bindXtextGeneratorNaming() { + * MyGeneratorNaming + * } + * } + **/ @SuppressWarnings("all") public class DefaultGeneratorModule extends AbstractGenericModule { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.java index 7ddbd3e48..915347270 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IGuiceAwareGeneratorComponent.java @@ -10,7 +10,9 @@ package org.eclipse.xtext.xtext.generator; import com.google.inject.Injector; /** - * @noreference + * The Xtext generator uses dependency injection with Guice + * for distributing the configuration to all its components. Instances of this interface can initialize + * themselves with a Guice injector, e.g. by calling {@code injector.injectMembers(this)}. */ @SuppressWarnings("all") public interface IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.java index 6d0bb9b4a..5b660a0c4 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorFragment.java @@ -11,8 +11,8 @@ import org.eclipse.xtext.xtext.generator.IGuiceAwareGeneratorComponent; import org.eclipse.xtext.xtext.generator.Issues; /** - * A fragment that contributes to the {@link XtextGenerator}. - * @noimplement + * A fragment that contributes to the {@link XtextGenerator}. Use {@link AbstractXtextGeneratorFragment} + * for implementing new fragments. */ @SuppressWarnings("all") public interface IXtextGeneratorFragment extends IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.java index d0cfc1bac..25e66bf9a 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/IXtextGeneratorLanguage.java @@ -14,7 +14,9 @@ import org.eclipse.xtext.xtext.generator.model.GuiceModuleAccess; import org.eclipse.xtext.xtext.generator.model.StandaloneSetupAccess; /** - * @noimplement + * Configuration for an Xtext language. Implemented by {@link XtextGeneratorLanguage}. + * + * @noimplement This interface should not be implemented by clients. */ @SuppressWarnings("all") public interface IXtextGeneratorLanguage { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/ImplicitFragment.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/ImplicitFragment.java index 508359621..4b3c11623 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/ImplicitFragment.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/ImplicitFragment.java @@ -27,6 +27,9 @@ import org.eclipse.xtext.xtext.generator.model.PluginXmlAccess; import org.eclipse.xtext.xtext.generator.model.TypeReference; import org.eclipse.xtext.xtext.generator.xbase.XbaseUsageDetector; +/** + * The ImplicitFragment is added in the first slot to all language configurations. + */ @SuppressWarnings("all") class ImplicitFragment extends AbstractStubGeneratingFragment { @Inject diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/Issues.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/Issues.java index a041d9c20..34aa4164b 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/Issues.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/Issues.java @@ -8,7 +8,7 @@ package org.eclipse.xtext.xtext.generator; /** - * @noreference + * Use this to report configuration problems during the {@link IXtextGeneratorFragment#checkConfiguration(Issues)} phase. */ @SuppressWarnings("all") public interface Issues { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/LanguageModule.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/LanguageModule.java index dfe6ec2cd..5834dd798 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/LanguageModule.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/LanguageModule.java @@ -16,6 +16,10 @@ import org.eclipse.xtext.xtext.RuleNames; import org.eclipse.xtext.xtext.generator.IXtextGeneratorLanguage; import org.eclipse.xtext.xtext.generator.XtextGeneratorLanguage; +/** + * Language-specific Guice module that is used in a child injector of the global injector + * derived from {@link DefaultGeneratorModule}. + */ @FinalFieldsConstructor @SuppressWarnings("all") class LanguageModule extends AbstractGenericModule { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/MweIssues.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/MweIssues.java index 8b7851d9f..bc031d070 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/MweIssues.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/MweIssues.java @@ -14,7 +14,7 @@ import org.eclipse.xtext.xtext.generator.Issues; import org.eclipse.xtext.xtext.generator.XtextGenerator; /** - * @noreference + * {@link Issues} implementation for MWE2 workflows. */ @FinalFieldsConstructor @SuppressWarnings("all") diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/StandardLanguage.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/StandardLanguage.java index cdac4145c..c3ad76cf2 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/StandardLanguage.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/StandardLanguage.java @@ -49,8 +49,24 @@ import org.eclipse.xtext.xtext.generator.xbase.XbaseGeneratorFragment2; import org.eclipse.xtext.xtext.generator.xbase.XtypeGeneratorFragment2; /** + * This specialization of the {@link XtextGeneratorLanguage} adds all the standard generator fragments + * that are commonly used for Xtext languages. This eliminates the need to list all these fragments + * explicitly in the workflow file. More fragments can be added as required, but the standard fragments + * cannot be removed. However, most of these fragments disable themselves automatically if they are + * not applicable, e.g. the {@link WebIntegrationFragment} does not generate anything if the web project + * is disabled in the project configuration. + * + *
The configuration for individual fragments can be made with the corresponding properties. + * For example, write + *
+ * formatter = formatting.Formatter2Fragment2 { + * generateStub = true + * } + *+ * to enable stub generation for the formatter. + * * @author Sven Efftinge - Initial contribution and API - * @noextend + * @noextend This class should not be extended by clients. */ @Accessors({ AccessorType.PUBLIC_SETTER, AccessorType.PROTECTED_GETTER }) @Log diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.java index a163a434f..d58a2db39 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextDirectoryCleaner.java @@ -29,7 +29,10 @@ import org.eclipse.xtext.xtext.generator.model.project.ISubProjectConfig; import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig; /** - * @noextend + * This component cleans all directories for generated code according to the project configuration + * (usually 'src-gen' for plain layout and 'src/main/xtext-gen' for Maven/Gradle layout). + * + * @noextend This class should not be extended by clients. */ @SuppressWarnings("all") public class XtextDirectoryCleaner implements IGuiceAwareGeneratorComponent { diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGenerator.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGenerator.java index 610b20262..c25d2c2be 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGenerator.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGenerator.java @@ -68,10 +68,28 @@ import org.eclipse.xtext.xtext.generator.model.project.BundleProjectConfig; import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig; /** - * The Xtext language infrastructure generator. Can be configured with {@link IXtextGeneratorFragment} - * instances as well as with some properties declared via setter or adder methods. + * The Xtext language infrastructure generator. Use the {@code configuration} block to add general + * configuration for your Xtext project and the generated code, e.g. + *
+ * configuration = { + * project = model.project.StandardProjectConfig { + * baseName = "org.example.language" + * rootPath = ".." + * } + * code = { + * encoding = 'ISO-8859-1' + * } + * } + *+ * You can generate code for one or more Xtext languages within the same project. For each language, + * add a {@code language} block, e.g. + *
+ * language = StandardLanguage { + * name = "org.example.language.MyExampleLanguage" + * } + ** - * @noextend + * @noextend This class should not be extended by clients. */ @Log @SuppressWarnings("all") diff --git a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.java b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.java index f1debd95b..ea42d9645 100644 --- a/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.java +++ b/org.eclipse.xtext.xtext.generator/xtend-gen/org/eclipse/xtext/xtext/generator/XtextGeneratorLanguage.java @@ -60,7 +60,19 @@ import org.eclipse.xtext.xtext.generator.model.StandaloneSetupAccess; import org.eclipse.xtext.xtext.generator.model.project.IXtextProjectConfig; /** - * @noextend + * Configuration for an Xtext language. Use this class if you need to specify exactly which generator + * fragments you want to include, or alternatively {@link StandardLanguage} to work with the standard + * fragments. + * + *
The most important property is {@code name}, which should be set to the language name exactly + * as specified in the grammar file. If the default grammar resolution based on the name does not + * work in your particular scenario, set the {@code grammarUri} property instead. Furthermore, + * use {@code fileExtensions} to specify the file extensions for your language.
+ * + *Generator fragments can be added with the {@code fragment} property. See {@link StandardLanguage} + * for a list of useful fragments.
+ * + * @noextend This class should not be extended by clients. */ @Log @SuppressWarnings("all") @@ -120,6 +132,10 @@ public class XtextGeneratorLanguage extends CompositeGeneratorFragment2 implemen @Inject private XtextGeneratorResourceSetInitializer resourceSetInitializer; + /** + * The URI of the grammar file. Use this property if the automatic grammar resolution based on {@link #setName(String)} + * does not work in your particular scenario. + */ public void setGrammarUri(final String uri) { this.grammarUri = uri; } @@ -138,14 +154,25 @@ public class XtextGeneratorLanguage extends CompositeGeneratorFragment2 implemen return _elvis; } + /** + * The language name exactly as specified in the grammar. + */ public void setName(final String name) { this.name = name; } + /** + * Either a single file extension or a comma-separated list of extensions for which the language + * shall be registered. + */ public void setFileExtensions(final String fileExtensions) { this.fileExtensions = IterableExtensions.