[MonoDevelop] Comments on the comment template

[Mike Krüger]

Hi

I've read your bug report and decided to do something about that - I 
admit that the generated description isn't helpful -
  but I've gone in the opposite direction ... the generated comment is 
now >really< verbose.

For the people who hate the auto description it's inserted as 2 steps - 
one undo will give an empty description.

Example of the current behavior:

If you've this method:

   public LineState GetLineState (int lineNumber)

and type /// you end up with:

/// <summary>
    /// Gets the state of the line.
    /// </summary>
    /// <returns>
    /// The line state.
    /// </returns>
    /// <param name='lineNumber'>
    /// Line number.
    /// </param>
    public LineState GetLineState (int lineNumber)

After the first undo you'll end up with:

    /// <summary>
    ///
    /// </summary>
    /// <returns>
    ///
    /// </returns>
    /// <param name='lineNumber'>
    ///
    /// </param>
    public LineState GetLineState (int lineNumber)
>
How about this - do we need a turn-off option then (I would prefer fewer 
options) ?

It also detects exceptions thrown - the rules used to generate the 
documentation are complicated and I don't know if I should expose them 
in the options panel or if interrested people should just mess around 
with the xml file.
The documentation generation can be improved - it would be nice if 
anyone could work on that since I won't have that much time for this 
feature during the 2.6 cycle.

Regards
Mike
>
> I found the xml comment template to be a little bit too verbose, so I 
> submitted the following bug.
>
> https://bugzilla.novell.com/show_bug.cgi?id=606222
>
> I got two replies, one agrees with me.
>
> The other does not agree and redirected me here, assuming I found the 
> right list.
>
> The question in short is: Why is the comment template for methods so 
> verbose:
>
> ///<param name="path">
> /// A<see cref="System.String"/>
> ///</param>
>
> I would consider the "A <see cref="System.String"/>" to be repetitive 
> since that information is already available in the code. Tools such as 
> intellisense do already include that information and I assume others 
> does as well.
>
> Does anyone have any ideas on this?
>
> How can this be changed, there seem to be some previous design 
> decision, but where can I find it?
>
>
> _______________________________________________
> Monodevelop-list mailing list
> Monodevelop-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/monodevelop-list
>    

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.ximian.com/pipermail/monodevelop-list/attachments/20100707/720dfa7a/attachment.html