Bug 320811

Description Alexander Nittka 2010-07-24 10:05:48 EDT

This is a compilation of (possible) errors in and suggestions for the Xtext documentation. It is based on the PDF-Version available for the 1.0.0 release.

-page 10 top in 2.1.6 Adding a Namespace Concept paragraph below data typr rule definition for Qualified name: ...figures out that the rule is a _data type rule_... (broken link/emphasis of data type rule)

-same paragraph: ... is done by so called ValueConverters... add a link to the explanation/examples for value converters

--page 10 bottom in 2.1.6 Adding a Namespace Concept before rule definition of Import: The declaration of the _Import_ rule should... (broken emphasis?)

-2.2 Processing Xtext Models: add information and examples for IUnitOfWork, EObjectHandle (how to get the EObject from it) etc.

-3.1 A First Example last paragraph: Note, that *none* of his implemenetations... (non->none)

-3.2.3 Rules list of phases: add "build index of visible elements for linking"?

-3.2.3.1 Terminal Rules, Return Types last paragraph: possibly also point to the default implementation

-3.2.3.2 EBNF Expressions, Character Ranges: add some information about allowed ranges (Unicode?)

-3.2.3.2 EBNF Expressions, Negated Tokens: the example does not work as ANY character is not equal to '*/'. If you want to express the ML_COMMENT rule using negation it would have to be something like
'/*' (!'*' | '*'!'/')+ '*/'

-3.2.3.2 EBNF Expressions, RuleCalls: don't use QUALIFIED_NAME as an example. This example hides ID and this type of definition is a major source of problems. If using this example, clearly state the impact of hiding ID and that usually one would use a data type rule for that. No simply DON'T use this example.

-3.2.4.1 EBNF Expressions, Unassigned Rule Calls, last paragraph: The rule in this example will never create an instance of AbstractToken directly.
But what if TokenX does not create one?

-3.2.6 Data Type Rules sentence "In addition when this has been defined as a ... ": (e.g. "foo/*..."). missing opening quotation marks as well as missing period after the sentence

-3.3.5. Customizing Post Processing, sentence The post processor expects... (if the name of the grammar file...): What if the grammar name is different? PostProcessor.ext seems to be quite independent of the grammar name.

-3.3.5: Customizing Post Processing, list of standard use cases: a simple example for each would be very helpful

-4.1.1: A Short Introduction to MWE2 first paragraph: An in-depth documentation can be found in chapter "MWE2"#MWE2. (broken link)

-5.4.1.3 Serializer page 42 bottom list (...which is something the parser doesn't always do): Orders within list-features can not be validated,.... instances of R1 and R1 (should be R1 and R2)

-5.5.2 Default Runtime Behaviour first sentence: ... it provides a many advantages. (should be: provides many advantages)

-5.6.1.1 Resource and EObject Descriptions last paragraph: ... we need to learn how thoes exported _IEObjectDescriptions_s... (broken link/broken emphasis)

-5.6.1.3 Global Scopes Based On Explicit Imports, last but one paragraph: ... for the type IGlobalScopeProvider by means of Guice:#dependencyInjaection. (broken link)

-5.6.2.1. Declarative Scoping: please go through the entire section and check correctness. I have found the following issues.
--3rd paragraph: Here TypeToReturn is the name of that type which also corresponds to the type parameter. (I don't see a *type* parameter in either signature)
--6th paragraph (page 54): ... the implementation will start looking for methods matching the other signature (with the EClass parameter).
what do you mean by "EClass parameter", as I see it both signatures differ only in the naming, not in the parameters. So the informationin parentheses is confusing


-5.6.3. Imported Namespace-Aware Scoping: inform the reader about the default assumptions (dot-separated namespace and * as wild card), which classes have to be overridden if the name space scheme is to be different

-5.7. Value Converter: there seems to be an implicit value converter also for data type rules, add a corresponding note to the documentation (which class is responsible)
--Is there a difference between value converters for terminal rules/datatype rules?

-5.10.2 Encoding at Language Runtime, last paragraph: sample for binding with the @Runtime annotation (either here or as general information in the Guice section)

-7.1.2 Label Providers For Index Entries, end of first paragraph: ..., i.e IResourceDescription, IEObjectDescription_, and IReferenceDescription. (broken emphasis for IEOD)

-7.3 QuickFixes first sentence: For validation written using the AbstractDeclarativeValidator:#custom_validation ... (broken link?)
--end of second paragraph: ... static String field _INVALID_TYPE_NAME_ (broken emphasis)
--end of third paragraph: ...new entries in the _plugin.xml___gen_ file (broken emphasis)
--beginning of forth paragraph: Continuing with the _INVALID_TYPE_NAME_ (broken emphasis)
--Quick fixes in general: add notes on quick fixes for syntactic and linking errors (can they be added, where to start digging)

-general: there is a paragraph on testing validation rules, similar hints for testing lexing/parsing, scoping, etc would be great. Maybe a section on testing in general would be useful (hints to existing code, general patterns for the setup etc.). I would find sample code for the lexing/parsing particularly important as many questions in the forum deal with "I get error 'expecting input...'", "how would my terminal rule have to look like to do such and such".