[Mono-dev] Documentation in Mono?

[Stefanos Apostolopoulos]

On Fri, 2010-01-08 at 21:58 +0200, huseyin cakir wrote:
> I am a newbie mono developer, I want to ask documentation tool you
> used?
> I searched about it and some recommends Sandcastle and some mdoc what
> you suggest that works best with mono-develop?


The compiler can parse xml comments in the source and turn them in a
standalone xml file that can be used by all .Net IDEs (MonoDevelop
included). For example, if you have Foo.dll and enable doc generation in
the project options, you will receive a Foo.xml that contains the inline
documentation for Foo, which will then show up inside the IDE.

For standalone documentation, the best options are Doxygen (which can
parse C#-style doc comments and turn them into a wide variety of
formats) and mdoc (which requires documentation to be maintained outside
the source code). Each approach has its advantages and disadvantages:
Doxygen is easier to use (just point it at your source and let it run)
and can produce HTML, latex, PDF and even CHM files easily, while mdoc
allows you to separate documentation from the source code (which is a
double-edged sword: while keeps the code clean and allows for
internationalization (which is less useful than it sounds), it also
makes it easier to let the comments get out of sync with the code).

Sandcastle is annoying to setup and is Windows-only, which kinda defeats
the purpose of using Mono in the first place.


-- 
> Hüseyin Çakır
> 
> Web: http://huseyincakir.freehostia.com/
> Blog: http://huseyincakir.wordpress.com/
> GoogleWave: huseyin.cakir35 at googlewave.com
> Alternative Mails: huseyincakir at iyte.edu.tr,
> huseyin.cakir at std.izmirekonomi.edu.tr
> 
> LEGAL NOTICE:
> This e-mail, links and any files included are confidential and
> intended solely for the attention and use of the individual or entity
> to which it is addressed. If you are not the intended recipient you
> are notified that disclosing, copying, distributing or taking any
> action in reliance on the contents of this information is strictly
> prohibited.
> 
> Please notify the sender immediately by e-mail if you have received
> this e-mail in error and permanently delete this e-mail and all its
> included files from your entire system immediately.
> 
> WARNING: 
> Computer viruses can be transmitted via e-mail and its included files.
> The recipient should check this e-mail and all included files for the
> presence of viruses. Hüseyin Çakır accepts no liability for any damage
> caused by any virus transmitted by this e-mail and its included files.
> E-mail transmission cannot be guaranteed to be secure or error-free as
> information could be intercepted, corrupted, lost, destroyed, arrive
> late or incomplete, or contain viruses. Hüseyin Çakır also does not
> accept any liability for e-mail messages sent to the addressee as a
> consequence of this e-mail message whether done so automatically or
> such requiring human intervention. The sender therefore does not
> accept liability for any errors or omissions in the contents of this
> message, which arise as a result of this e-mail transmission. Thanks
> for your attention.
> 
> _______________________________________________
> Mono-devel-list mailing list
> Mono-devel-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-devel-list