Uploaded image for project: 'OFBiz'
  1. OFBiz
  2. OFBIZ-7537

Complete the documentation in the XSD files

    XMLWordPrintableJSON

    Details

    • Type: Improvement
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: Trunk
    • Fix Version/s: None
    • Component/s: ALL COMPONENTS
    • Labels:
      None

      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>
      

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                diveshdut Divesh Dutta
                Reporter:
                jacques.le.roux Jacques Le Roux
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated: