[Mono-docs-list] Predefined docs patch
Martin Willemoes Hansen
mwh@sysrq.dk
Tue, 14 Oct 2003 12:29:20 +0200
--=-ywxPcLe71uwSAmIhF4Dp
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
On Mon, 2003-10-13 at 23:40, Duncan Mak wrote:
> Hello Martin!
>
> On Mon, 2003-10-13 at 09:32, Martin Willemoes Hansen wrote:
> > I was copying and pasting a lot when describing finalizers and the 3
> > internal constructors.
>
> First off, I'd like to say thank you for writing this patch.
NP.
> The patch looks fine, but I'd rather keep the updater general for now,
> because the plan is to use it for generating non-Gtk# docs as well (i.e.
> augment the existing ECMA corlib docs and generating docs for other
> platform libraries).
Ahh I see.
> You're very right that it is extremely tedious to cut and paste a lot of
> the same stuff, but it is also very easy to write one-off programs to do
> the cut-n-pasting for you. In fact, every time I had to do something
> like that (mass-documenting the internal IntPtr constructor, or the
> Finalize method, etc), I wrote a little program to do it for me. It
> really is not that painful.
Point taken, when I think of it this sounds like the way to go.
> > This patch will do the hard work in the updater.exe stage.
>
> I feel that we should not be doing this work in updater.exe; we should
> have a fixer script for doing this work instead. I posted something for
> fixing the signature of Finalize in bug #47016 last night and maybe we
> should generalize the script by having it take an XPath expression and a
> string and then do something like this:
>
> XmlNodeList results = document.SelectNodes (input_expression);
>
> foreach (XmlNode node in results)
> node.InnerText = input_string;
>
> I think such this fixer should fulfill most use cases, without making
> updater specific to Gtk# docs.
Ahh that would be nice, is your fixer tool in cvs? If not maybe a good
place to put it, is in gtk-sharp/doc/fixertool
> > What do you think?
>
> Do you understand why I'm reluctant to commit this patch? Do you think
> writing such a fixer program will be sufficient to handle the problems
> (the tediousness) you're seeing?
Yes I think that would be doable.
> thanks,
>
> Duncan.
I was also thinking a bit about cleaning the dir: mono/monodoc/generator
Like removing: a.cs, b.cs and all.xml, then clean the makefile for the
test, gtk-docs, update-docs and *.trees section
Based on my assumtion that gtk# docs are build in the gtk# src dir, and
other docs are built in their own dirs.
I would like to make this cleanup if its okay with you. I can probably
have a patch ready today.
Also is generator.cs used?
--
Martin Willemoes Hansen
--------------------------------------------------------
E-Mail mwh@sysrq.dk Website mwh.sysrq.dk
IRC MWH, freenode.net
--------------------------------------------------------
--=-ywxPcLe71uwSAmIhF4Dp
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 7bit
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8">
<META NAME="GENERATOR" CONTENT="GtkHTML/3.0.9">
</HEAD>
<BODY>
On Mon, 2003-10-13 at 23:40, Duncan Mak wrote:
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>Hello Martin!
On Mon, 2003-10-13 at 09:32, Martin Willemoes Hansen wrote:
> I was copying and pasting a lot when describing finalizers and the 3
> internal constructors.
First off, I'd like to say thank you for writing this patch.</PRE>
</BLOCKQUOTE>
<PRE></I></FONT></PRE>
NP.<BR>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>The patch looks fine, but I'd rather keep the updater general for now,
because the plan is to use it for generating non-Gtk# docs as well (i.e.
augment the existing ECMA corlib docs and generating docs for other
platform libraries).</PRE>
</BLOCKQUOTE>
<PRE></I></FONT></PRE>
Ahh I see.<BR>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>You're very right that it is extremely tedious to cut and paste a lot of
the same stuff, but it is also very easy to write one-off programs to do
the cut-n-pasting for you. In fact, every time I had to do something
like that (mass-documenting the internal IntPtr constructor, or the
Finalize method, etc), I wrote a little program to do it for me. It
really is not that painful.</PRE>
</BLOCKQUOTE>
<PRE></I></FONT></PRE>
Point taken, when I think of it this sounds like the way to go.<BR>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>> This patch will do the hard work in the updater.exe stage.
I feel that we should not be doing this work in updater.exe; we should
have a fixer script for doing this work instead. I posted something for
fixing the signature of Finalize in bug #47016 last night and maybe we
should generalize the script by having it take an XPath expression and a
string and then do something like this:
XmlNodeList results = document.SelectNodes (input_expression);
foreach (XmlNode node in results)
node.InnerText = input_string;
I think such this fixer should fulfill most use cases, without making
updater specific to Gtk# docs.</PRE>
</BLOCKQUOTE>
<PRE></I></FONT></PRE>
Ahh that would be nice, is your fixer tool in cvs? If not maybe a good place to put it, is in gtk-sharp/doc/fixertool<BR>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>> What do you think?
Do you understand why I'm reluctant to commit this patch? Do you think
writing such a fixer program will be sufficient to handle the problems
(the tediousness) you're seeing?</PRE>
</BLOCKQUOTE>
<PRE></I></FONT></PRE>
Yes I think that would be doable.<BR>
<BR>
<BLOCKQUOTE TYPE=CITE>
<PRE><FONT COLOR="#737373"><I>thanks,
Duncan.</I></FONT></PRE>
</BLOCKQUOTE>
<BR>
I was also thinking a bit about cleaning the dir: mono/monodoc/generator<BR>
Like removing: a.cs, b.cs and all.xml, then clean the makefile for the test, gtk-docs, update-docs and *.trees section<BR>
Based on my assumtion that gtk# docs are build in the gtk# src dir, and other docs are built in their own dirs.<BR>
I would like to make this cleanup if its okay with you. I can probably have a patch ready today.<BR>
<BR>
Also is generator.cs used?
<PRE><TABLE CELLSPACING="0" CELLPADDING="0" WIDTH="100%">
<TR>
<TD>
<PRE>--
Martin Willemoes Hansen
--------------------------------------------------------
E-Mail mwh@sysrq.dk Website mwh.sysrq.dk
IRC MWH, freenode.net
--------------------------------------------------------
</PRE>
</TD>
</TR>
</TABLE>
</PRE>
</BODY>
</HTML>
--=-ywxPcLe71uwSAmIhF4Dp--