ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bugzi...@apache.org
Subject [Bug 1477] New - enh.: add column for value type in Parameter/attribute tables
Date Tue, 24 Apr 2001 15:08:24 GMT
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: ant-dev@jakarta.apache.org                                   |
+ |  Reported By: Daniel.Barclay@digitalfocus.com                              |
+ |      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.)

Mime
View raw message