ES-DOC / esdoc-cim-v2-schema

Canonical CIM schema v2 definition
2 stars 5 forks source link

Line wrapping for readability of long descriptions #46

Closed sadielbartholomew closed 3 years ago

sadielbartholomew commented 3 years ago

Some of the descriptions for properties are very long but there is no line-wrapping on them, resulting very long lines of >400 character length in some cases, making the CIM more difficult to comprehend at a glance. I suggest for readability an good code style we break up the descriptions in a similar way to the following, from (automated tools like 'black' don;t seem to do this automaticallyeven when given a set line-length to enforce, sadly, unless there is already line breaking of some sort):

    return {
    ...
        'properties': [
            ('coupling_cost', 'float', '0.1',
             'Coupling cost measures the overhead caused by coupling. This can include... [long description].'),
    ...
            ]
    }

to:

    return {
    ...
        'properties': [
            (
                 'coupling_cost', 'float', '0.1',
                 'Coupling cost measures the overhead caused by coupling. '
                 'This can include... [long description] '
                 '[more long description] ... '
                 '[more long description] ... '
                 '[more long description].'
            ),
    ...
            ]
    }

where Python's implicit line joining inside parentheses ensures a single string is recognised as the description.

davidhassell commented 3 years ago

I'm all for this.