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

[Michal Moskal]

On 11/10/06, Ildar Mulyukov <ildar at users.sourceforge.net> wrote:
> 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).

IMHO they have different advantages. Writing and maintaining external
documentation takes more effort and time, if written by the
programmer. The programmer needs to open external file to write it and
later remember to change it, when he changes the source code. OTOH it
doesn't involve documentation writer (if separate from programmer)
changing the source code and it is easier to maintain several language
versions of documentation. So it makes perfect sense for widely used
libraries which are going to have documentation written by external
contributors in several languages, and which also doesn't change very
much over time (I mean that methods mostly keep doing the same for
backward compatibility).

This should also work for Nemerle standard library, to some extent, if
we had the manpower to do that.

However, when you're writing a small project and want documentation
mostly for yourself or two other fellow programmers, writing external
XML documentation seems an overkill.

-- 
   Michał