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

[Igor Tkachev]

Hello Andrey,

>> + the only way to keep documentation up to date and to control
>>   reference integrity.
> I use doxygen and find it not very messy.

Does it check references at the compile time?

>> 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).

If we do it, it will be great. However, I am not sure we need to have
any options for this. Maybe it is possible to mix both approaches.

>> 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).

This is personal preferences. Other developers may have other
preferences.

> 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.

The correctness should be checked by the compiler. It works like an
include.

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