[Mono-docs-list] External docs preliminary example

[Joe Betz]

--=-zUw5FdRchH9p0Cdm+UVs
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

Adam, Gaurav and the rest of the Mono docs team:

Attached is a section of inline documentation I had written for
System.Web.UI.WebControls.AdRotator converted to an external xml file.

I created the file form my limited understanding of C Sharp and what
I've gathered from the list about external documentation.

As I understand it, the external XML should merge easily with the stub
XML to create mono XML that describes a source file completely.  So
basicly, external XML needs to:

  * Encapsulate comments in tags that uniquely identify type and class
    but not assembly since the directory will tell us that, right?

  * Distinguish between methods with the same name but different
    parameters and return values.

  * Reside in a file with the same name as the source file in
    directory parallel to the source directory.  For my example:
    /mcs/class/System.Web/System.Web.UI.WebControls-en/AdRotator.xml

Attached is an extended example.  Below is a snippet of that example.

Am in in the right direction?  I hope to start writing docs soon and
would appriciate any input as soon as possible.

Cheers,

Joe Betz



-- filename: System.Web.UI.WebControls-en/AdRotator.xml --
<!DOCTYPE ...>
<class name="AdRotator">
  <remarks>
    Adds an advertisement into the HTML page.  The advertisement is
    selected at random from an XML file or through a call-back ...
  </remarks>

  <class name="AdRecord">
    <remarks>
      Records an advertisement's statistics
    </remarks>

    <member name="keyword" type="string">
      <summary>
        The keyword of the recorded advertisement.
      </summary>
    </member>

    <method name="LoadAdFile">
      <summary>
        Reads an advertisement XML file and returns
        an array of <c>AdRecord</c>'s.
      </summary>

      <param type="string">
        <c>file</c> is the URL of the XML file to read.
      </param>

      <returns type="AdRecord">
        <c>AdRecord[]</c> of all the advertisements in the
        XML file
      </returns>
    </member>

  </class>
</class>



--=-zUw5FdRchH9p0Cdm+UVs
Content-Disposition: attachment; filename=AdRotator.xml
Content-Transfer-Encoding: quoted-printable
Content-Type: text/xml; charset=ISO-8859-1

<!DOCTYPE ...>=0D
<class name=3D"AdRotator">=0D
  <remarks>=0D
    Adds an advertisement into the HTML page.  The advertisement is=0D
    selected at random from an XML file or through a call-back=0D
    event. The frequency at which each advertisement appears is set in=0D
    the XML file.  The XML file also stores the image displayed, the=0D
    URL the advertisment navigates to, and the advertisments alternate=0D
    text.=0D
  </remarks>=0D
=0D
  <member name=3D"advertismentFile" type=3D"string">=0D
    <summary>=0D
      The URI of the XML file that advertisments will be randomly=0D
      selected from.=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <member name=3D"AdCreatedEvent" type=3D"object">=0D
    <summary>=0D
      ??=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <member name=3D"alternateText" type=3D"string">=0D
    <summary>=0D
      Alternate text for the advertisement.  Will be set values during=0D
      (On)PreRender-ing.=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <member name=3D"imageUrl" type=3D"string">=0D
    <summary>=0D
      URL for the advertisment's image.  Will be set values during=0D
      (On)PreRender-ing.=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <member name=3D"navigateUrl" type=3D"string">=0D
    <summary>=0D
      URL the advertisement navigates to.  Will be set values during=0D
      (On)PreRender-ing.=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <member name=3D"fileDirectory" type=3D"string">=0D
    <summary>=0D
      The directory where the advertisment XML files are stored.=0D
    </summary>=0D
  </member>=0D
 =20=0D
  <class name=3D"AdRecord">=0D
    <remarks>=0D
      Records an advertisement's statistics=0D
    </remarks>=0D
=0D
    <member name=3D"adProps" type=3D"IDictionary">=0D
      <summary>=0D
        The details of the recorded advertisement=0D
      </summary>=0D
    </member>=0D
=0D
    <member name=3D"hits" type=3D"int">=0D
      <summary>=0D
        The number of hits (or impressions or clicks) recorded for the=0D
        advertisement=0D
      </summary>=0D
    </member>=0D
=0D
    <member name=3D"keyword" type=3D"string">=0D
      <summary>=0D
        The keyword of the recorded advertisement.=0D
      </summary>=0D
    </member>=0D
=0D
    <method name=3D"AdRecord">=0D
      <summary>=0D
        Construct an <c>AdRecord</c>=0D
        instance initialized to (<paramref name=3D"adProps"/>).=0D
      </summary>=0D
=0D
      <param type=3D"IDictionary">=0D
        <c>adProps</c> is an <c>IDictionary</c> of the properties of an=0D
        advertisement: <c>alternateText</c>, <c>navigateUrl</c>,=0D
        <c>imageUrl</c>, <c>Keyword</c> and <c>Impressions</c>.=0D
      </param>=0D
    </method>=0D
=0D
    <method name=3D"LoadAdFile">=0D
      <summary>=0D
        Reads an advertisement XML file and returns=0D
        an array of <c>AdRecord</c>'s.=0D
      </summary>=0D
=0D
      <param type=3D"string">=0D
        <c>file</c> is the URL of the XML file to read.=0D
      </param>=0D
=0D
      <returns type=3D"AdRecord[]">=0D
        <c>AdRecord[]</c> of all the advertisements in the=0D
        XML file=0D
      </returns>=0D
    </member>=0D
    <member name=3D"fStream" type=3D"fStream">=0D
      <summary>=0D
        Stream to read in the XML file.=0D
      </summary>=0D
    </member>=0D
=0D
    <member name=3D"list" type=3D"ArrayList">=0D
      <summary>=0D
        Parser's <c>ArrayList</c> list of <c>hybridDict</c>'s=0D
        each list item is an advertisement.=0D
      </summary>=0D
    </member>=0D
=0D
    <member name=3D"reader" type=3D"XmlReader">=0D
      <summary>=0D
        Parser's <c>XMLReader</c>.  This reads data for=0D
       the <c>document</c>.=0D
      </summary>=0D
    </member>=0D
  </class>=0D
</class>
--=-zUw5FdRchH9p0Cdm+UVs--