Re: [ndoc-devel] change proposal: AutoSummarizePropertyFields

[Jason D. <ja...@in...>]

Ryan Seghers <rse...@ca...> wrote:

> I guess the only issue is the non-standard elements, and I don't have much
> perspective on that.  The downside I suppose is compatibility with MS, if
> they fix their documenter.  But my approach has the same liability, and
also
> has the other disadvantages you mentioned.  So I'd say your approach is
> generally better than mine.

Their documenter will just ignore elements that it doesn't understand. It's
not possible to reproduce MSDN documentation without extra elements to act
as hints for our documenter. In fact, pre-1.0 versions of the XML help files
that Microsoft released with the Fx even included "non-standard" elements
that are very similiar to ours. Being able to add non-standard elements is a
huge advantage in my opinion.

> I'm pretty lazy, though.  I like to automate everything I commonly do.  So
> from my perspective, I'd like the references to the interfaces to be
> automated too.  I understand the disadvantages you mentioned.  Also,
there's
> the disadvantage that my method means that I have no comments for some
> things in my source code (the backer fields and the implementations of the
> interface).  So someone reading my source has less information.  That's a
> pretty major drawback to my approach.

I'm lazy, too. And I think that in this case, we might not need to insert
any elements. There either is a connection (like from a class to an
implemented interface) or one can be inferred (like your property to field
naming conventions). I agree that those types of documentation should be
copied or augmented automatically.

> I think what I'd really like is a separate tool that inserts/modifies the
> XML comments in C# code, and can do things like I want such as
automatically
> generate the property backer refs and the interface refs.  Then NDoc stays
> pure and the source code ends up with all the xml comments.

I'm not saying we should have to do this--the NDoc source code is already
anything put pure! If you already did the work to get the backer refs
inserted then I say check it in (as long as it's an option).

Jason