[Mono-docs-list] Updating mdvalidator

[Jonathan Pryor]

On Wed, 2006-11-01 at 05:50 -0500, Joshua Tauberer wrote:
> <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.

Excellent point.

I'll add all the new elements to the XSD then.

 - Jon