IDE Issue 4
From MemberWiki
Contents |
IDE Issue 4: Long description and/or short description
Original write-up
Should we have one description field for describing the widgets, or perhaps two description fields (one short and one long), or perhaps something else?
Existing industry practice
- Ext.js 2.0 uses JSDoc to document their widgets and only includes a single short descriptive summary as part of the class definition
- Dojo 1.0 (i.e., dijit) has no inline documentation about its widget set
- Adobe has a requirement for a short name (<=23 characters?) to fit on their palettes.
- Apple Dashboard Info.plist file has a non-localizable CFBundleName and a localizable CFBundleDisplayName
- Google Gadgets
<module>file has a single string, thetitleattribute on the<ModulePrefs>element.
Jon's proposed recommendation
Our metadata should include both a short description and a long description . The short description field would be optional and localizable; if not provided, IDEs SHOULD construct a short description automatically using available information, such as using the JavaScript class name (e.g., "Ext.Button"). The long description would be required and localizable.
There is still a question about what to call these two things (i.e., "description" and "title"). Here is a bit of research:
- HTML has two attributes for short description, 'title' attribute that sometimes is rendered as a tooltip by browsers, and an 'alt' that is used as a short descriptive string for accessibility of images, and then a 'longdesc' which holds a link to a long description (only for images)
- SVG has a <title> element for a short description and a <desc> element for a long description
- XForms has a <hint> element for a short description and a <help> element for a long description
This is all arbitrary, but how about <title> (matches HTML's attribute and SVG's element) and <description> (matches Aptana)
Also matches the W3C widget spec --chaals 20:10, 2 January 2008 (PST)
