[nem-en] Documentation comments clarification and proposals [Long]

[Igor Tkachev]

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.

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.

So, it's not good, but we must have it.

BTW, C# supports includes for XML documentation, so it could be taken
out of source code, but it still remains XML.

-- 
Best regards,
 Igor                            mailto:it at rsdn.ru