[Mono-docs-list] Predefined docs patch

Duncan Mak duncan@ximian.com
Mon, 13 Oct 2003 17:40:11 -0400

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.

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

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.

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

> 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?