Re: [Banshee-devel-list] BCE documentation

[Frank <funtastix googlemail com>]

Before I could form an opinion on that, two assumptions first:

1. How are the Banshee docs created? I certainly don't have to do it
by hand, right? Using mdoc as well and then editing in monodoc? I
think I have read about that.

2. It seems, that with the docs installed in monodoc I will also get
those code comments in monodevelop, is that correct?

Given those two assumptions hold true,I would not mind switching to
the proposed way of doing things, I would not even have to do much, as
the XML for LiveRadio and StreamRecorder seems already correct (the
files generated with mdoc from the compiled doc.xml), so all I'd have
to do is delete the inline XML comments and copy the files (glad I
saved them) to the docs dir, I assume. I would then update the wiki
accordingly.

There is only one thing I worry about just a bit: The way I usually
work, inline comments have one great workflow advantage: Whenever I
change/add code I can add my comments in the same place using the same
tool (monodevelop) rather than doing my work, then updating the docs
afterwards (mdoc-update, right?) and editing in another tool
(monodoc). Lazyness could prevent good documentation much more... see
the Banshee docs, that are mostly VERY empty... Using the way Bertrand
proposed, is there any better workflow possible?

2010/4/6 Bertrand Lorentz <bertrand lorentz gmail com>:
> Hi, late reply below
>
> On Mon, 2010-03-29 at 12:08 +0700, Frank wrote:
>> I've created a new wiki page:
>> http://www.gitorious.org/banshee-community-extensions/pages/MonodocBuilding
>> describing what I did. I am not very good with Makefiles/build
>> systems, so there might be a much better way to compile the initial
>> doc.xml file. I tried using the Compiler option in MonoDevelop without
>> success. Maybe adding a doc target to Makefile.am would be the way to
>> go, but I don't know exactly how to do it correctly. Any improvement
>> is very welcome.
>>
>> Furthermore, is it a good idea to push the resulting doc to a "doc"
>> directory in the repository?
>
> I started working on integrating code docs in the build system, copying
> stuff from the Banshee build system, as usual. It should make generating
> and updating docs quite less painful than what is decribed on the wiki.
>
> In the LiveRadio extension, the doc is in xml comments inside the code,
> which brings several problems, practical and esthetical :
> 1/ When the XML comments are processed using the -doc option of gmcs,
> any missing bit of XML or anything that looks like bad XML (like the
> e-mail addresses in the file headers) generates a warning.
> As we build with the "warnaserror" flag by default, this make the build
> fail.
> 2/ Inline docs make source files needlessly verbose, as the objective of
> those docs is to be browsed outside of the code, using monodoc
>
> My suggestion would be to have the code documentation live in separate
> XML files, like we do in Banshee (see the docs/ directory). Those XML
> files would be committed to the git repository and included in the
> source tarball.
>
> Frank and others, what do you think about this ?
> If we're OK, I'll commit the relevant bits for the build system.
>
> --
> Bertrand
>
>> Frank
>>
>> 2010/3/28 Mathijs Dumon <mathijsken hotmail com>:
>> > Hey Frank,
>> >
>> > I'd be very interested in that! Thumbs up by me.
>> >
>> > mathijs
>> >
>> >> Date: Sun, 28 Mar 2010 11:58:26 +0700
>> >> From: funtastix googlemail com
>> >> To: Banshee-devel-list gnome org
>> >> Subject: [Banshee-devel-list] BCE documentation
>> >>
>> >> Hi all,
>> >>
>> >> I've created some monodoc documentation from my xml comments for the
>> >> Banshee.LiveRadio Extension. Is there any good place to put it? It's
>> >> just a bit more convinient to browse than the code itself and it's
>> >> actually not hard to produce. Will do the same for
>> >> Banshee.StreamRecorder. If anyone is interested in a short summary of
>> >> how I did it, I'll extend the wiki by a page describing this. It cost
>> >> me no time to produce the doc, but lots of time to find out HOW to do
>> >> it.
>> >>
>> >> BR
>> >>
>> >> Frank
>
> _______________________________________________
> Banshee-devel-list mailing list
> Banshee-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/banshee-devel-list
>
>