[Mono-docs-list] Updating mdvalidator

[Joshua Tauberer]

(Note my new email address, btw.)

Jonathan Pryor wrote:
> Currently mdvalidator doesn't like the documentation for generic
> types/members, as the XSD that mdvalidator uses hasn't been updated for
> the new XML tags like <typeparam/>.  This is to be expected.
> 
> However, some non-ECMA tags were added to the output of monodocer, in
> particular the /Type/TypeParameters, /Type/TypeParameters/TypeParameter,
> and /Type/Base/BaseTypeArguments elements added in October 9.
> 
> I think we'll need to add /Type/Base/BaseTypeArguments to the XSD to
> permit validation, but do we need the <TypeParameters/> element?  This
> seems to just duplicate the information already
> within /Type/Docs/typeparam.
> 
> Is this correct?  Would it be possible to remove <TypeParameters/> and
> instead use <typeparam/>

<typeparam> duplicates <TypeParameters> in just the same way <param>
duplicates <Parameter>.  It happens to be particularly useful when
(type-)parameter names change: It's trivial for monodocer to update the
(Type)Parameter nodes (by deleting and inserting new ones, for
instance), but updating (type)param nodes is not possible because you
don't always know which of the old parameters corresponds to which of
the new parameters.  The approach taken has been to not touch param
nodes, but to update Parameter nodes.

For example, you had:
  <Parameter Name="X"/>
  <param name="x">This is the important parameter.</param>

And then you change the method from having an X parameter to having Y
and Z parameters.  On the next monodocer run, what do you do with the
existing param node?  You shouldn't delete it because you don't want to
delete user-written docs.  Probably you leave it alone until the doc
writer can resolve what happened:

  <Parameter Name="Y"/>
  <Parameter Name="Z"/>
  <param name="x">This is the important parameter.</param>
  <param name="y">...</param>
  <param name="z">...</param>

Obviously that's not the only approach one could take (and maybe not the
best), but that's what's happening (iirc).

Also, it has been my feeling that the order of nodes in the Docs section
should not be relied on for anything (although that may not be what's
happening everywhere), and so you would need a separate list of type
parameters to make sure you have the right order somewhere.

-- 
- Joshua Tauberer

http://razor.occams.info

"Strike up the klezmer and start acting like a man. You're
about to have a truth-mitzvah."  -- The Colbert Report