http://nagoya.apache.org/bugzilla/show_bug.cgi?id=1477
*** shadow/1477 Tue Apr 24 08:08:24 2001 --- shadow/1477.tmp.16068 Tue Apr 24 08:08:24 2001 *************** *** 0 **** --- 1,100 ---- + +============================================================================+ + | enh.: add column for value type in Parameter/attribute tables | + +----------------------------------------------------------------------------+ + | Bug #: 1477 Product: Ant | + | Status: NEW Version: 1.3 | + | Resolution: Platform: PC | + | Severity: Normal OS/Version: | + | Priority: Component: Documentation | + +----------------------------------------------------------------------------+ + | Assigned To: [EMAIL PROTECTED] | + | Reported By: [EMAIL PROTECTED] | + | CC list: Cc: | + +----------------------------------------------------------------------------+ + | URL: http://jakarta.apache.org/ant/manual/CoreTasks/*.html | + +============================================================================+ + | DESCRIPTION | + In the documentation pages for tasks (the Built-In Tasks and Optional + Tasks) sections, in the tables describing attributes, it would probably + help if the tables had a column that indicated the data type or possible + values for each attribute. + + Having an explicit column would help documentation authors remember to + document the data types or possible values of attributes. + + Having clearer and more complete documentation would reduce the need to + guess and experiment to figure out what's required, letting users proceed + more directly to using Ant to get the job done. + + (Note that one reason explicit documentation is important is that those + data types and values are not as obvious to all users as an experienced + user/developer/documenter might think. + + For example, note that some boolean attributes take "yes" and "no", some + take "true" and "false", some take "on" and "off". + + Now consider an attribute whose description implies that it's a boolean + attribute, but specifies nothing else. For example, see JavaDoc's nohelp + attribute, whose description says only: + + Do not generate help link + + How can the user know which value ("yes"? "true"?) is needed to activate + the feature? (Or might just the presence of the attribute suppress the + help link?) + + Some other specific examples: + - Chmod.perm: Is the form "go+rw" supported? + - Jar.whenempty: The Parameters table says only "Behavior to use if no files + match." (The table doesn't list the possible values.) + + ) + + + Having this data-type information consistently would improve the quality of + the documentation and make Ant easier to use. + + Having a specific column for the data-type information would remind authors + to provide the information. + + + Also, providing a listing of common type descriptions in a table up front + might make it easier for authors by providing pre-written text for them to + use in their tasks' tables. + + Here's a partial listing: + - "true"/"false" boolean + - "yes"/"no" boolean + - "on"/"off" boolean + - (relative or absolute) file or directory pathname + - (relative or absolute) file pathname + - (relative or absolute) directory pathname + - property name + - (qualified) class name (not class _file_ name as written in many places) + - (qualified) general resource name + - comma-separated list of file names + - file name pattern + - comma-separated list of file name patterns + - path element (Jar file name / class/resource root directory name) + - search path (colon-/semi-colon separated list of path elements) + - path ID + - pattern ID + - target name + - integer for milliseconds + - enumeration of values that are specific to the task and the attribute + (e.g., Apply's "type' attribute, with "file", "dir", "both"; FixCRLF's + "cr" attribute with "add", "asis", "remove") + - other general string value that is specific to the task and the attribute + (e.g., Cvs's "command" attribute, Echo's "message" atribute) + + + + Another idea would be to have a template or recommended convenitions for + documenting Ant tasks. If authors followed it, that would enhance + consistency and make things clear. + + (Inconsistencies such as sometimes used fixed-width font for values but + other times using italics makes it a little harder for readers to + recognize what the documentation is trying to convey. Sometimes having + attribute documentation prose above the table but sometimes below makes + it a little harder to find information.)
