(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
_______________________________________________
Mono-docs-list maillist - Mono-docs-list lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
|