Home » Archived » XML Schema Definition (XSD) » Treatment of annotation documentation in ecore builder
| Treatment of annotation documentation in ecore builder [message #28019] |
Thu, 04 September 2003 10:21  |
Eclipse User |
|
|
|
Originally posted by: ihc.sas-glas.mottmac.com
Hi,
It appears to us that XSDEcoreBuilder ignores user information in an
annotation - is this true?
i.e. if a schema element has:
<xsd:annotation>
<xsd:documentation>Comment about the meaning of this type
</xsd:documentation>
</xsd:annotation>
I think that XSD picks it up (I can at least navigate to an Element called
"documentation" although I haven't yet extracted the value)
but in navigating the resulting ecore model we can find no corresponding
item. Default XMI serialisation of the ecore model does not contain the
text.
Isn't this supported by the XSDEcoreBuilder?
If not, is it planned to be? (It's pretty important to us)
Ian
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #28058 is a reply to message #28019] |
Thu, 04 September 2003 10:38  |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
Ian,
It's interesting you ask this because I just finished sending a note to
someone else asking this same question. We do ignore it right now, but it is
definitely a work item on our list (for the 2.0 stream) to be able to carry
over XML Schema documentation into the Ecore model and then reproduce it in
the generated Javadoc. Is it just documentation you are concerned about, or
appinfo as well? Do you think it's reasonable to expect that any
documentation contents can simply be "dumped" into a Javadoc comment and hence
be processed as Javadoc HTML?
Ian Cornwell wrote:
> Hi,
>
> It appears to us that XSDEcoreBuilder ignores user information in an
> annotation - is this true?
>
> i.e. if a schema element has:
>
> <xsd:annotation>
> <xsd:documentation>Comment about the meaning of this type
> </xsd:documentation>
> </xsd:annotation>
>
> I think that XSD picks it up (I can at least navigate to an Element called
> "documentation" although I haven't yet extracted the value)
>
> but in navigating the resulting ecore model we can find no corresponding
> item. Default XMI serialisation of the ecore model does not contain the
> text.
>
> Isn't this supported by the XSDEcoreBuilder?
> If not, is it planned to be? (It's pretty important to us)
>
> Ian
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #28097 is a reply to message #28058] |
Thu, 04 September 2003 11:22 |
| Eclipse User |
|
|
|
Originally posted by: ihc.sas-glas.mottmac.com
Ed,
Our priority at present is on user info. (Appinfo might be a nice to have
- I'm not sure what schema we will encounter - but we'd rather have user
info sooner rather than waiting on appinfo).
We are not using EMF for code generation. Javadoc HTML sounds fine for
codegen but we would expect a plain text string in the Ecore model.
I'm glad to hear that the feature is planned. Since the design of one of
our next tasks may depend on exactly where the user info appears in the
ecore model, we would very much appreciate if the implementers were able
to tell us, before release, where the user info will appear. Our guess is
that it will be in an EAnnotation with a "details" entry pair of something
like {"documentation", [value]}, but the same EAnnotation as the one
currently used for "representation" etc or a separate one, or somewhere
else entirely? Knowing the intended design will help us a lot.
Thanks,
Ian
Ed Merks wrote:
> Ian,
> It's interesting you ask this because I just finished sending a note to
> someone else asking this same question. We do ignore it right now, but it
is
> definitely a work item on our list (for the 2.0 stream) to be able to carry
> over XML Schema documentation into the Ecore model and then reproduce it in
> the generated Javadoc. Is it just documentation you are concerned about, or
> appinfo as well? Do you think it's reasonable to expect that any
> documentation contents can simply be "dumped" into a Javadoc comment and
hence
> be processed as Javadoc HTML?
> Ian Cornwell wrote:
> > Hi,
> >
> > It appears to us that XSDEcoreBuilder ignores user information in an
> > annotation - is this true?
> >
> > i.e. if a schema element has:
> >
> > <xsd:annotation>
> > <xsd:documentation>Comment about the meaning of this type
> > </xsd:documentation>
> > </xsd:annotation>
> >
> > I think that XSD picks it up (I can at least navigate to an Element called
> > "documentation" although I haven't yet extracted the value)
> >
> > but in navigating the resulting ecore model we can find no corresponding
> > item. Default XMI serialisation of the ecore model does not contain the
> > text.
> >
> > Isn't this supported by the XSDEcoreBuilder?
> > If not, is it planned to be? (It's pretty important to us)
> >
> > Ian
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #28135 is a reply to message #28058] |
Thu, 04 September 2003 13:17 |
 Dave Carlson
Messages: 34
Registered: July 2009 |
Member |
|
|
Hi Ed,
You should also plan for xsd:documentation content that contains XML markup,
not only plain text. A growing number of schemas use a customized XML tag
set to structure their documentation (and this is almost always the case for
appinfo content).
For example, the current schemas from the OASIS Universal Business Language
(UBL) use documentation like the following. They are debating the doc
contents, but will definitely use XML markup. They have also prototyped
using XHTML markup in the doc value.
<ccts:ABIE dictionaryEntryName="Order. Details" definition="information
directly relating to the order." qualifierTermObjectClassTerm=""
objectClassTerm="Order" qualifierTerm_PropertyTerm="" propertyTerm="Details"
representationTerm="Details" />
Similarly, the IRS using XML markup in the <schema> tag documentation in one
of their large schema sets:
<Description>IRS e-file Corporate Income Tax Schema - IRS Form
4466</Description>
<TaxYear>2002</TaxYear>
<MaturityLevel>Final Release</MaturityLevel>
<ReleaseDate>April 30, 2003</ReleaseDate>
Can you put the serialized DOM node in the eCore annotation value? When
output to JavaDoc, this poses another challenge...
Cheers,
Dave Carlson
"Ed Merks" <merks@ca.ibm.com> wrote in message
news:3F571641.3914C7C8@ca.ibm.com...
> Ian,
>
> It's interesting you ask this because I just finished sending a note to
> someone else asking this same question. We do ignore it right now, but
it is
> definitely a work item on our list (for the 2.0 stream) to be able to
carry
> over XML Schema documentation into the Ecore model and then reproduce it
in
> the generated Javadoc. Is it just documentation you are concerned about,
or
> appinfo as well? Do you think it's reasonable to expect that any
> documentation contents can simply be "dumped" into a Javadoc comment and
hence
> be processed as Javadoc HTML?
>
>
> Ian Cornwell wrote:
>
> > Hi,
> >
> > It appears to us that XSDEcoreBuilder ignores user information in an
> > annotation - is this true?
> >
> > i.e. if a schema element has:
> >
> > <xsd:annotation>
> > <xsd:documentation>Comment about the meaning of this type
> > </xsd:documentation>
> > </xsd:annotation>
> >
> > I think that XSD picks it up (I can at least navigate to an Element
called
> > "documentation" although I haven't yet extracted the value)
> >
> > but in navigating the resulting ecore model we can find no corresponding
> > item. Default XMI serialisation of the ecore model does not contain the
> > text.
> >
> > Isn't this supported by the XSDEcoreBuilder?
> > If not, is it planned to be? (It's pretty important to us)
> >
> > Ian
>
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #28255 is a reply to message #28097] |
Fri, 05 September 2003 20:41 |
| Eclipse User |
|
|
|
Originally posted by: merks.ca.ibm.com
Ian,
Sorry I haven't responded more quickly. The note from Dave gave me pause for
thought. The idea of sticking a potentially huge string into the details map
isn't all that appealling so I was thinking it would probably be one doc line per
map entry and each key would be numbered, 0, 1, 2. Since EMap is ordered, the
order would be maintained correctly. A nicer alternative would be simply to nest
the DOM contents directly within the EAnnotation as Dave was suggesting. Although
this isn't possible with the support in 1.1.0/1.1.1, in the 2.0 stream there will
be support for mixed unvalidated XML content so it will be a possible
alternative. I can't say for sure which way we will go right now but we will take
a position in the coming weeks.
The primary motivation for support this
Ian Cornwell wrote:
> Ed,
> Our priority at present is on user info. (Appinfo might be a nice to have
> - I'm not sure what schema we will encounter - but we'd rather have user
> info sooner rather than waiting on appinfo).
>
> We are not using EMF for code generation. Javadoc HTML sounds fine for
> codegen but we would expect a plain text string in the Ecore model.
>
> I'm glad to hear that the feature is planned. Since the design of one of
> our next tasks may depend on exactly where the user info appears in the
> ecore model, we would very much appreciate if the implementers were able
> to tell us, before release, where the user info will appear. Our guess is
> that it will be in an EAnnotation with a "details" entry pair of something
> like {"documentation", [value]}, but the same EAnnotation as the one
> currently used for "representation" etc or a separate one, or somewhere
> else entirely? Knowing the intended design will help us a lot.
>
> Thanks,
> Ian
>
> Ed Merks wrote:
>
> > Ian,
>
> > It's interesting you ask this because I just finished sending a note to
> > someone else asking this same question. We do ignore it right now, but it
> is
> > definitely a work item on our list (for the 2.0 stream) to be able to carry
> > over XML Schema documentation into the Ecore model and then reproduce it in
> > the generated Javadoc. Is it just documentation you are concerned about, or
> > appinfo as well? Do you think it's reasonable to expect that any
> > documentation contents can simply be "dumped" into a Javadoc comment and
> hence
> > be processed as Javadoc HTML?
>
> > Ian Cornwell wrote:
>
> > > Hi,
> > >
> > > It appears to us that XSDEcoreBuilder ignores user information in an
> > > annotation - is this true?
> > >
> > > i.e. if a schema element has:
> > >
> > > <xsd:annotation>
> > > <xsd:documentation>Comment about the meaning of this type
> > > </xsd:documentation>
> > > </xsd:annotation>
> > >
> > > I think that XSD picks it up (I can at least navigate to an Element called
> > > "documentation" although I haven't yet extracted the value)
> > >
> > > but in navigating the resulting ecore model we can find no corresponding
> > > item. Default XMI serialisation of the ecore model does not contain the
> > > text.
> > >
> > > Isn't this supported by the XSDEcoreBuilder?
> > > If not, is it planned to be? (It's pretty important to us)
> > >
> > > Ian
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #577149 is a reply to message #28019] |
Thu, 04 September 2003 10:38 |
Ed Merks
Messages: 33137
Registered: July 2009 |
Senior Member |
|
|
Ian,
It's interesting you ask this because I just finished sending a note to
someone else asking this same question. We do ignore it right now, but it is
definitely a work item on our list (for the 2.0 stream) to be able to carry
over XML Schema documentation into the Ecore model and then reproduce it in
the generated Javadoc. Is it just documentation you are concerned about, or
appinfo as well? Do you think it's reasonable to expect that any
documentation contents can simply be "dumped" into a Javadoc comment and hence
be processed as Javadoc HTML?
Ian Cornwell wrote:
> Hi,
>
> It appears to us that XSDEcoreBuilder ignores user information in an
> annotation - is this true?
>
> i.e. if a schema element has:
>
> <xsd:annotation>
> <xsd:documentation>Comment about the meaning of this type
> </xsd:documentation>
> </xsd:annotation>
>
> I think that XSD picks it up (I can at least navigate to an Element called
> "documentation" although I haven't yet extracted the value)
>
> but in navigating the resulting ecore model we can find no corresponding
> item. Default XMI serialisation of the ecore model does not contain the
> text.
>
> Isn't this supported by the XSDEcoreBuilder?
> If not, is it planned to be? (It's pretty important to us)
>
> Ian
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #577195 is a reply to message #28058] |
Thu, 04 September 2003 11:22 |
| Eclipse User |
|
|
|
Originally posted by: ihc.sas-glas.mottmac.com
Ed,
Our priority at present is on user info. (Appinfo might be a nice to have
- I'm not sure what schema we will encounter - but we'd rather have user
info sooner rather than waiting on appinfo).
We are not using EMF for code generation. Javadoc HTML sounds fine for
codegen but we would expect a plain text string in the Ecore model.
I'm glad to hear that the feature is planned. Since the design of one of
our next tasks may depend on exactly where the user info appears in the
ecore model, we would very much appreciate if the implementers were able
to tell us, before release, where the user info will appear. Our guess is
that it will be in an EAnnotation with a "details" entry pair of something
like {"documentation", [value]}, but the same EAnnotation as the one
currently used for "representation" etc or a separate one, or somewhere
else entirely? Knowing the intended design will help us a lot.
Thanks,
Ian
Ed Merks wrote:
> Ian,
> It's interesting you ask this because I just finished sending a note to
> someone else asking this same question. We do ignore it right now, but it
is
> definitely a work item on our list (for the 2.0 stream) to be able to carry
> over XML Schema documentation into the Ecore model and then reproduce it in
> the generated Javadoc. Is it just documentation you are concerned about, or
> appinfo as well? Do you think it's reasonable to expect that any
> documentation contents can simply be "dumped" into a Javadoc comment and
hence
> be processed as Javadoc HTML?
> Ian Cornwell wrote:
> > Hi,
> >
> > It appears to us that XSDEcoreBuilder ignores user information in an
> > annotation - is this true?
> >
> > i.e. if a schema element has:
> >
> > <xsd:annotation>
> > <xsd:documentation>Comment about the meaning of this type
> > </xsd:documentation>
> > </xsd:annotation>
> >
> > I think that XSD picks it up (I can at least navigate to an Element called
> > "documentation" although I haven't yet extracted the value)
> >
> > but in navigating the resulting ecore model we can find no corresponding
> > item. Default XMI serialisation of the ecore model does not contain the
> > text.
> >
> > Isn't this supported by the XSDEcoreBuilder?
> > If not, is it planned to be? (It's pretty important to us)
> >
> > Ian
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #577211 is a reply to message #28058] |
Thu, 04 September 2003 13:17 |
Dave Carlson
Messages: 34
Registered: July 2009 |
Member |
|
|
Hi Ed,
You should also plan for xsd:documentation content that contains XML markup,
not only plain text. A growing number of schemas use a customized XML tag
set to structure their documentation (and this is almost always the case for
appinfo content).
For example, the current schemas from the OASIS Universal Business Language
(UBL) use documentation like the following. They are debating the doc
contents, but will definitely use XML markup. They have also prototyped
using XHTML markup in the doc value.
<ccts:ABIE dictionaryEntryName="Order. Details" definition="information
directly relating to the order." qualifierTermObjectClassTerm=""
objectClassTerm="Order" qualifierTerm_PropertyTerm="" propertyTerm="Details"
representationTerm="Details" />
Similarly, the IRS using XML markup in the <schema> tag documentation in one
of their large schema sets:
<Description>IRS e-file Corporate Income Tax Schema - IRS Form
4466</Description>
<TaxYear>2002</TaxYear>
<MaturityLevel>Final Release</MaturityLevel>
<ReleaseDate>April 30, 2003</ReleaseDate>
Can you put the serialized DOM node in the eCore annotation value? When
output to JavaDoc, this poses another challenge...
Cheers,
Dave Carlson
"Ed Merks" <merks@ca.ibm.com> wrote in message
news:3F571641.3914C7C8@ca.ibm.com...
> Ian,
>
> It's interesting you ask this because I just finished sending a note to
> someone else asking this same question. We do ignore it right now, but
it is
> definitely a work item on our list (for the 2.0 stream) to be able to
carry
> over XML Schema documentation into the Ecore model and then reproduce it
in
> the generated Javadoc. Is it just documentation you are concerned about,
or
> appinfo as well? Do you think it's reasonable to expect that any
> documentation contents can simply be "dumped" into a Javadoc comment and
hence
> be processed as Javadoc HTML?
>
>
> Ian Cornwell wrote:
>
> > Hi,
> >
> > It appears to us that XSDEcoreBuilder ignores user information in an
> > annotation - is this true?
> >
> > i.e. if a schema element has:
> >
> > <xsd:annotation>
> > <xsd:documentation>Comment about the meaning of this type
> > </xsd:documentation>
> > </xsd:annotation>
> >
> > I think that XSD picks it up (I can at least navigate to an Element
called
> > "documentation" although I haven't yet extracted the value)
> >
> > but in navigating the resulting ecore model we can find no corresponding
> > item. Default XMI serialisation of the ecore model does not contain the
> > text.
> >
> > Isn't this supported by the XSDEcoreBuilder?
> > If not, is it planned to be? (It's pretty important to us)
> >
> > Ian
>
|
|
|
| Re: Treatment of annotation documentation in ecore builder [message #577288 is a reply to message #28097] |
Fri, 05 September 2003 20:41 |
Ed Merks
Messages: 33137
Registered: July 2009 |
Senior Member |
|
|
Ian,
Sorry I haven't responded more quickly. The note from Dave gave me pause for
thought. The idea of sticking a potentially huge string into the details map
isn't all that appealling so I was thinking it would probably be one doc line per
map entry and each key would be numbered, 0, 1, 2. Since EMap is ordered, the
order would be maintained correctly. A nicer alternative would be simply to nest
the DOM contents directly within the EAnnotation as Dave was suggesting. Although
this isn't possible with the support in 1.1.0/1.1.1, in the 2.0 stream there will
be support for mixed unvalidated XML content so it will be a possible
alternative. I can't say for sure which way we will go right now but we will take
a position in the coming weeks.
The primary motivation for support this
Ian Cornwell wrote:
> Ed,
> Our priority at present is on user info. (Appinfo might be a nice to have
> - I'm not sure what schema we will encounter - but we'd rather have user
> info sooner rather than waiting on appinfo).
>
> We are not using EMF for code generation. Javadoc HTML sounds fine for
> codegen but we would expect a plain text string in the Ecore model.
>
> I'm glad to hear that the feature is planned. Since the design of one of
> our next tasks may depend on exactly where the user info appears in the
> ecore model, we would very much appreciate if the implementers were able
> to tell us, before release, where the user info will appear. Our guess is
> that it will be in an EAnnotation with a "details" entry pair of something
> like {"documentation", [value]}, but the same EAnnotation as the one
> currently used for "representation" etc or a separate one, or somewhere
> else entirely? Knowing the intended design will help us a lot.
>
> Thanks,
> Ian
>
> Ed Merks wrote:
>
> > Ian,
>
> > It's interesting you ask this because I just finished sending a note to
> > someone else asking this same question. We do ignore it right now, but it
> is
> > definitely a work item on our list (for the 2.0 stream) to be able to carry
> > over XML Schema documentation into the Ecore model and then reproduce it in
> > the generated Javadoc. Is it just documentation you are concerned about, or
> > appinfo as well? Do you think it's reasonable to expect that any
> > documentation contents can simply be "dumped" into a Javadoc comment and
> hence
> > be processed as Javadoc HTML?
>
> > Ian Cornwell wrote:
>
> > > Hi,
> > >
> > > It appears to us that XSDEcoreBuilder ignores user information in an
> > > annotation - is this true?
> > >
> > > i.e. if a schema element has:
> > >
> > > <xsd:annotation>
> > > <xsd:documentation>Comment about the meaning of this type
> > > </xsd:documentation>
> > > </xsd:annotation>
> > >
> > > I think that XSD picks it up (I can at least navigate to an Element called
> > > "documentation" although I haven't yet extracted the value)
> > >
> > > but in navigating the resulting ecore model we can find no corresponding
> > > item. Default XMI serialisation of the ecore model does not contain the
> > > text.
> > >
> > > Isn't this supported by the XSDEcoreBuilder?
> > > If not, is it planned to be? (It's pretty important to us)
> > >
> > > Ian
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
Goto Forum:
Current Time: Sat Apr 20 00:09:45 GMT 2024
Powered by FUDForum. Page generated in 0.03730 seconds |
] 
Search
Help
Register
Login
Home
