[Chameleon-dev] [Bug 74] Change the "descXXXX.txt" documentation file to a more extensible format (XML ?)

[bugzilla-daemon@www.maptools.org]

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

spencer@dmsolutions.ca changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|spencer@dmsolutions.ca      |darren_redfern2000@hotmail.c
                   |                            |om



------- Additional Comments From spencer@dmsolutions.ca  2003-11-04 11:42 -------
Darren, good start.  I have given it a quick read and it looks like an excellent
framework.  There are a few issues that will need to be dealt with as we go, but
I think we have the basics.

I need some feedback from Sacha on widget Events (previously undocumented),
these do need to be integrated.  Also from Sacha, any other feedback on the
structure would be appreciated.

My initial comments:

1. (formatting issue) some of the sample tags have commas between the
attributes, ie:

<widgetdoc name="WidgetName", group="WidgetGroup">
                            ^
this is not valid XML.

2. language tag will not need a 'default' attribute

3. the purpose of attribute type attribute is not clear to me.  I expect this is
coming from the attribute groups in the existing documentation?  This happened
because many widgets happened to share these 'base' attributes because they
inherit functionality and state from the Widget class.  It seemed to me that
there was no point in documenting these 'base' attributes in every widget. 
Inheritance is, unfortunately, not the only mechanism by which these shared
attributes are included.  We will need to introduce an additional attribute in
the widgetdoc to indicate 'inheritance' (parentClass="Widget" for example).  We
will also need to introduce an additional tag like <includes/> that indicates
that a widget 'includes' common attributes (and javascript and HTML) from some
source.  These 'includes' could be documented separately.  They are not full
widgets but they supply similar functionality.  For example, there is a utility
class called Link.php that provides a widget with the ability to launch some
arbitrary code when activated.  I would image that we would have Link.doc.xml
and in a widget that uses Link.php, we would have <includes target="Link"/> ..
this would be a simple href to the Link entry on the output page.

4. there is no notation for capturing 'sub tags'.  Sub tags are valid XML tags
contained within the widget tag, for instance:

<cwc2 type="quickzoom">
  <zoom ..../>
</cwc2>

There is no way to document the sub tags "zoom" in the current system and this
needs to be added to the new system.  In this example, the "zoom" tag could have
an arbitrary number of attributes.  We have not yet nested more than one level,
but it is also possible, so our system should be capable of handling it.  I
suggest "<childtags>" that contains 0 or more <tag> entries.  This makes me
think that we need a <tag> level in the main widget doc.  So the new structure
could be:

<widgetdoc>
  <tag>
    <attribute name=""
type="[string|stringlist|integer|float|boolean|rgbcolor|hexcolor]"
mandatory="[true|false]">
      <description></description>
      <values> <!-- for string list -->
        <value name=""/>
      </values>
      <range start="" end=""/> <!-- for integer/float -->
    </attribute>
    <children>
      <tag/>
    <children>
  </tag>
</widgetdoc>

5. javascript functions can take parameters.  These should be documented also:

<jsfunction name="NavSetActiveTool">
  <description>
  Set the active navigation tool for a particular group of tools.
  </description>
  <parameters>
    <parameter name="" type="[expected variable type (string, int, array,
object, etc]" default="">description here</parameter>
  </parameters>
</jsfunction>     

6. There are a number of places where you have used something like jsfuncdesc, I
would prefer to use <description>.  If we ever get around to building a schema
for this document (which we should), then this will be much easier.  A
description will always follow the same rules.  All elements that will follow
the same rules for nesting and content should be called the same thing.

7. Nesting elements.  Not sure about this, but in general I think it may be
nicer to nest multiple elements inside a container element.  For instance:

<tags>
  <tag/>
  <tag/>
</tags>

rather than
<tag/>
<tag/>

While it looks a little more verbose, I think it would display more nicely in an
xml editor because you can 'collapse' the <tags> element to work on other
things.  I think it will also be easier for validation (schema) and for
programmatically generating the output.

I think I will leave it there for now :)  Can you make these changes and then
incorporate widget Events when Sacha provides info on them to you.




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