[Chameleon-dev] [Bug 743] [Chameleon - doc builder] Button attributes are not all extracted from Button.php

[bugzilla-daemon at www.maptools.org]

http://www.maptools.org/bugzilla/show_bug.cgi?id=743





------- Additional Comments From pspencer at dmsolutions.ca  2004-11-01 19:58 -------
The description of the SharedResource is not entirely accurate I guess.  Take,
for instance, the projection shared resource.  The elements of that
SharedResource cannot be used as part of the Projection or ProjectionLabel
widget, nor would it make sense to.  The issue here is that you want to make
everything behave consistently regardless of whether there is a good reason to
do so or not.  In this case, there is absolutely no technical benefit to making
these attributes available as part of a widget tag.  They would not be useful
and would, in fact, only cause confusion on the part of the user.  

It was my understanding that there was a place in the documentation structure to
document the contents of SharedResources associated with widgets.  This is the
place that the buttonizer SharedResource should be documented, if anywhere.

I am against adding more and more attributes just for the sake of making it
appear more consistent, when in fact I would never condone the use of the
attributes as part of the widget.

Also note that the documentation builder is limited in what it can automatically
discover about the widgets.  SharedResource structure and contents is not
currently coded in such a way as to expose it to the documentation building
process.  By way of example, every attribute that a widget can accept in the
cwc2 tag is 'registered' with the widget so that the widget code can
automatically verify the attribute and its content.  There is no registration of
SharedResource contents.  SharedResources are simply a placeholder for some
unstructured information.  Widgets can choose to interpret this in any
convenient way.  The use of XML within a SharedResource in the template is a
convention that is useful, but not necessary.  

What is, perhaps, missing is a mechanism for the widgets to declare the contents
of SharedResources in a way that can be validated (as widget attributes are
declared and validated).  I would see this as a useful change as it would allow:

1. more complete automated verification of templates
2. support for automatically documenting SharedResource structure associated
with widgets.

This would require a moderate amount of new development and should be considered
a new feature, which likely means that it should not be entertained for 1.99/2.0
at this point.  However, if we are going to do it, then it should be done for
beta 3.



------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.