[nem-en] Re: Re[2]: Documentation comments clarification and proposals[Long]

[Andrey Khropov]

Igor Tkachev wrote:

> Hello Michal,
> 
> > I strongly object to write any XML by hand (XML is for machines, not
> > us, pure human beings!), so I'm finding the proposal very appealing.
> 
> I agree with you. However, the problem is you need different sections
> to document different thinks: remarks, exceptions, parameters, etc.

> Finally, you will invent just another XML, which is not a good point.
Well I actually think than this is the problem.
XML is a good model to represent information (in fact it is what is now called
XML InfoSet) but its usual serialization is a mess for humans.
So, yes, I'd like to see lighter syntax with the same meaning because it makes
sense for me.

The same reason why you should probably prefer writing
--------------------------------------------
namespace MyNamespace
{
    public class MyClass
    {
        public static void Main()
        {
            Console.WriteLine("Hello, C#");
        }
    }
}
--------------------------------------------

instead of 
--------------------------------------------
<CsamlFile xmlns="http://schemas.microsoft.com/winfx/2006/xaml/csaml"
           xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <NamespaceDeclaration Identifier="MyNamespace">
        <ClassDeclaration Identifier="MyClass" 
                          Access="Public">
            <MethodDeclaration Identifier="Main" 
                               Access="Public" 
                               Modifier="Static" 
                               ReturnType="{x:Type void}">
                <InvocationExpression
                  MemberAccess="System.Console.WriteLine">
                    <InvocationExpression.ArgumentList>
                        <Literal Type="{x:Type string}"
                                 Value="Hello, CSAML! ">
                    </InvocationExpression.ArgumentList>
                </InvocationExpression>
            </MethodDeclaration>
        </ClassDeclaration>
    </NamespaceDeclaration>
</CsamlFile>
--------------------------------------------
(taken from http://www.charlespetzold.com/etc/CSAML.html) :-)

> 
> I tried XML documentation to document some of my stuff and I found it:
> 
> - leading to a source code mess.
> + the only way to keep documentation up to date and to control
>   reference integrity.
I use doxygen and find it not very messy.

> So, it's not good, but we must have it.
I think we should have C# XML as a one option
and have another style (simpler to write but fully semantically equivalent) as
another option (like we do with {}-based and indentation based syntax styles).

> 
> BTW, C# supports includes for XML documentation, so it could be taken
> out of source code, but it still remains XML.
It's good for describing examples and general concepts.
But I strongly believe documentation for meaning of fields, parameters, return
values and exceptions that can be thrown should be in a program (and should be
easy to write, otherwise nobody will ever want to write it).

Otherwise (external) it is harder to check correctness (you will almost always
need a good deal of parsing to do that) and it will soon become obsolete.

-- 
AKhropov