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

[Ildar Mulyukov]

	Hello,

On 10.11.2006 07:16:27, Igor Tkachev wrote:
>>  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.

Exactly. Thinking on the question, I've come to agree with Mono Team to  
C# documentation: http://mono-project.com/Generating_Documentation
Shortly, this approach'es idea is to have separate files for  
documentation, which are ready to be used with browsers: monodoc or  
web. Using the monodoc, you can also edit documentation in GUI  
(gtk-sharp).
My opinion is that a developer uses 3 sources of information for 3  
different purposes:
1. Documentation, as a main reference. For this point it's important to  
have a good documentation browser with, at least, index of  
classes/methods/etc. Monodoc is OK, I think.
2. Snippets and testcases, as a manual how to use particular  
class/method.
3. Source code (nemerle tree or mono tree), if none of the above helped.

Conclusion: my vote is to have documentation separate.

Regards, Ildar.

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

-- 
Ildar  Mulyukov,  free SW designer/programmer
================================================
email: ildar at users.sourceforge.net
projects: http://os-development.sourceforge.net/
home: http://tuganger.narod.ru/
ALT Linux Sisyphus
================================================