[jira] [Updated] (OFBIZ-7537) Complete the documentation in the XSD files

[Nicolas Malin (Jira)]

     [ https://issues.apache.org/jira/browse/OFBIZ-7537?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Jacques Le Roux updated OFBIZ-7537:
-----------------------------------
    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:
{code}
    <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>
[...]
{code}
{code}
            <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>
{code}

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>

{code}

  was:
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:
{code}
    <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>
[...]
{code}
{code}
            <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>
{code}

BTW I personnaly prefer this formatting when the lines are long
{code}
    <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>
{code}

> Complete the documentation in the XSD files
> -------------------------------------------
>
>                 Key: OFBIZ-7537
>                 URL: https://issues.apache.org/jira/browse/OFBIZ-7537
>             Project: OFBiz
>          Issue Type: Improvement
>          Components: ALL COMPONENTS
>    Affects Versions: Trunk
>            Reporter: Jacques Le Roux
>            Assignee: Divesh Dutta
>
> 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:
> {code}
>     <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>
> [...]
> {code}
> {code}
>             <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>
> {code}
> 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>
> {code}

--
This message was sent by Atlassian JIRA
(v6.3.4#6332)