Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » XML Schema Definition (XSD) » Treatment of annotation documentation in ecore builder
Treatment of annotation documentation in ecore builder [message #28019] Thu, 04 September 2003 06:21 Go to next message
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 06:38 Go to previous messageGo to next message
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 07:22 Go to previous messageGo to next message
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 09:17 Go to previous messageGo to next message
Dave Carlson is currently offline 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 16:41 Go to previous message
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 06:38 Go to previous message
Ed Merks is currently offline Ed Merks
Messages: 26014
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
Re: Treatment of annotation documentation in ecore builder [message #577195 is a reply to message #28058] Thu, 04 September 2003 07:22 Go to previous message
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 09:17 Go to previous message
Dave Carlson is currently offline 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 16:41 Go to previous message
Ed Merks is currently offline Ed Merks
Messages: 26014
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
Previous Topic:Weird namespaces when moving objects between XSD schemas
Next Topic:help with ref attribute
Goto Forum:
  


Current Time: Sat Aug 30 22:37:35 EDT 2014

Powered by FUDForum. Page generated in 0.02015 seconds