[ xframe-Bugs-1101707 ] Enumeration name missing in enum documentation

Bugs item #1101707, was opened at 2005-01-13 16:27
Message generated for change (Comment added) made by kriede
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454391&aid=1101707&group_id=48863

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: all platforms
Group: xsddoc-0.6-beta
>Status: Closed
>Resolution: Postponed
Priority: 5
Submitted By: Nobody/Anonymous (nobody)
Assigned to: Kurt Riede (kriede)
Summary: Enumeration name missing in enum documentation

Initial Comment:
Example: this type declaration

    <xsd:simpleType name="EarlyInvoicingMode" 
id="EarlyInvoicingMode">
        <xsd:annotation>
            <xsd:documentation>Possible early invoicing 
modes of a shop.
            </xsd:documentation>
        </xsd:annotation>

        <xsd:restriction base="xsd:NCName">
            <xsd:enumeration value='approved'>
                <xsd:annotation>
                    <xsd:documentation>
<p>
Early invoicing is disabled for this shop.<br/>
Invoices must be approved before they may be 
dispatched.
</p>
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:enumeration>
            <xsd:enumeration value='disabled'>
                <xsd:annotation>
                    <xsd:documentation>
<p>
Early invoicing is disabled for this shop.<br/>
Invoices may be created after processing has been 
completed</p>
                    </xsd:documentation>
                </xsd:annotation>
            </xsd:enumeration>
        </xsd:restriction>  
    </xsd:simpleType>

Produces this documentation

-----------------------------------------
Possible early invoicing modes of a shop.

Early invoicing is disabled for this shop.
Invoices must be approved before they may be 
dispatched. 

Early invoicing is disabled for this shop.
Invoices may be created after processing has been 
completed
--------------------------------------------

This is not very helpful because the name of the 
documented enumeration is not visible





----------------------------------------------------------------------

>Comment By: Kurt Riede (kriede)
Date: 2005-10-15 22:07

Message:
Logged In: YES 
user_id=484961

converted to feature request [1327624] documentation of 
enumeration values:
https://sourceforge.net/tracker/index.php?
func=detail&aid=1327624&group_id=48863&atid=454394

----------------------------------------------------------------------

Comment By: Nobody/Anonymous (nobody)
Date: 2005-01-25 17:43

Message:
Logged In: NO 

I think that documentation without the information WHAT is 
documented is absolutely useless.

I found this effect at the following places:

1.) when an enumeration is documented (as described)

2.) when attributes of a complex type are documented. 
The description of each attribute appears (also) in the 
genereal "Documentation" at the beginning of the page 
(before the documentation of the individual attributes). I 
think tha attribute documentation should only be visible at 
the attribute, but not repeated in teh global documentation.



----------------------------------------------------------------------

Comment By: Kurt Riede (kriede)
Date: 2005-01-14 18:00

Message:
Logged In: YES 
user_id=484961

As far as I understand you, it would be nice to have the 
possible value together with the documentation. Similar things 
can happen in a lot of other schema constructs.

So far we are following the XML Schema Infoset which 
specifies, that the documentation of a component is the 
summary of all nested documentation tags within a 
declaration.

I agree with your suggestion that sometimes the context of 
the documentation is lost. I'll think about if it is possible and 
helpfull (also with a reasonable effort) to add some context 
information to the documentation section.

Regards
Kurt

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454391&aid=1101707&group_id=48863


-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl