Community
Participate
Working Groups
The documentation on the extended EMF supported through annotations is just about non-existent within Eclipse. The two draft documents in the EMF Overviews are interesting, but worryingly dated. Please at least a) ensure that the drafts are referenced from standard EMF documentation so that Help searches find links to them. b) revise them, so that they identify themselves as "EMF 2.3.0-aligned draft" Ideally their content would be incorporated in a more comprehensive fashion. For instance, I would like to know the list of all elements of the http:///org/eclipse/emf/ecore/util/ExtendedMetaData namespace and what their role is. The best that seems available is a list of elements that may be used in XSD files. The remainder such as e.g. ecore:kind require reverse engineering the partial descriptions. (The description is 'this pattern is resolved by these magic values', not 'this value has this effect'.) We need a per element description that identifies - role as genmodel input for a Model plugin - role as genmodel input for an Edit plugin - role as genmodel input for an Editor plugin - role as XSD annotation - interaction with other elements - constraints on validity when used by genmodel
We're not likely to do much beyond updating http://www.eclipse.org/modeling/emf/docs/overviews/XMLSchemaToEcoreMapping.pdf. The EMF book touches on all these topics and more, but we expect the community to help contribute towards the type of documentation they would find useful if what we provide isn't already that. We've had one person, Dave, focus on documentation (i.e., the book) for effectively a whole release cycle, which is basically 1/3 of the development staff (Dave, Marcelo, me); that is about the most that I can do towards complete documentation. Once that's done, I hope we can make a few of the chapters available on the website, such as the one that covers @model annotations XML Schema Ecore annotations. So we'll review this bugzilla in and summer, but it's unlikely we'll produce a document of the type you describe. The community has been quite vocal about wanting more and more, especially documentation, but we can only produce so much...
It was only an enhancement request - I do sympathise; hence the initial suggestions to just make existing material accurate and accessible. I think you forget how old the EMF book is. EMF has improved dramatically since 1.1. I'm afraid that I have been very disappointed by the book because it omits all the interesting dark corners that I have wanted to know about; ESuperAdapter, EMOF*, *ExtendedMetaData. It was only when I googled that I found the EMF overview docs. The community may produce good secondary tutorial material, but I doubt that anyone other than you can really produce the primary reference material that describes the full sensitivity of genmodel to annotations and magic spellings. If nothing else, the JavaDoc for EAnnotation should lead to brief definitions of annotation namespaces, in similar style to the JavaDoc for System.getProperties(). My problem is that I'm trying to produce an Ecore model of Ecore's EMOF including the annotations represented as xmi:Extensions. So I'm not using XSD at all, just starting with Ecore and trying to work magic. Once I read the whole of the XML Schema paper to discover all the magic annotations, I suddenly realised that it may be easy; just load XMI.xsd as an EMF project and copy. At least I hope it's now easy. I very much doubt that I could have concocted xmi.ecore from scratch. It's the difficulty of doing that that prompts the enhancement request.
Ed, No, I know that book is really old, and EMF has changed a lot. So that's why it's literally taken the better part of a year to update it and expand it to cover lots of stuff in more detail. But I know exactly what the next complaint will be, it doesn't cover EMF 2.3, and since the impact of that is pervasive, updating for that would take another year. So we'll always be behind, unless we stop moving the code forward... Wizards to help specify the annotations would be nice too: https://bugs.eclipse.org/bugs/show_bug.cgi?id=143478
Tagging this with bugday and helpwanted in case anyone wants to contribute something here...
With the new validation support, it's easier to author well-formed tags. Unless someone else writes documentation this will never be done.
Done.
