[OFBIZ-7537] Complete the documentation in the XSD files

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Works for Me
• Affects Version/s: Trunk
• Component/s: ALL COMPONENTS
• Assignee: Divesh Dutta
• Reporter: Jacques Le Roux
• Created: 22/Jun/16 09:38
• Updated: 11/Jan/22 09:37
• Resolved: 29/Aug/20 17:12

Description

We have already some documentation in the XSD files, but we could clearly do better, and that's an important point to achieve a higher adoption by new comers. And you know what? We need them

Thanks to Paul Piper for a reminder on the subject

When I speak about documentation I speak about the blocks you can find in XSDs elements and attributes like in widget-form.xsd:

    <xs:element name="display-entity" substitutionGroup="AllFields">
        <xs:annotation>
            <xs:documentation>This is just like display but looks up a description using the Entity Engine; note that if also-hidden is true then it uses the key as the value, not the shown description.</xs:documentation>
        </xs:annotation>
[...]

            <xs:attribute type="xs:integer" name="size">
                <xs:annotation>
                    <xs:documentation>Specifies the size of the field (as a number of characters), when the text to display exceed the given size it is truncated and add the complete text as a hint</xs:documentation>
                </xs:annotation>
            </xs:attribute>

BTW I personnaly prefer this formatting when the lines are long

    <xs:element name="display-entity" substitutionGroup="AllFields">
        <xs:annotation>
            <xs:documentation>
                This is just like display but looks up a description using the Entity Engine; 
                note that if also-hidden is true then it uses the key as the value, not the shown description.
            </xs:documentation>
        </xs:annotation>
[...]
            <xs:attribute type="xs:integer" name="size">
                <xs:annotation>
                    <xs:documentation>
                        Specifies the size of the field (as a number of characters), 
                        when the text to display exceed the given size it is truncated and add the complete text as a hint
                     </xs:documentation>
                </xs:annotation>

Issue Links

• is a child of: OFBIZ-10285 OFBiz Documentation Global Task