[Gtk-sharp-list] ToggleButton Doc and Example

Lee Mallabone gnome@fonicmonkey.net
25 Apr 2003 09:06:30 +0100

On Fri, 2003-04-25 at 04:04, John Luke wrote:
> The example is inline with the documentation. I included it as a
> seperate file as well because the wiki page says:
> Which I took as it would need to be a seperate file as well, but
> probably isn't necessary. Which way is preferred?

What I have been trying to do so far, is to include just 1 or 2 example
*methods* inline, and then reference a complete C# file as well.

As I see it, this has a bunch of benefits:

1) The user gets to see a short, simple example *immediately* in the
class overview.
2) The user gets to see the example methods in the context of a complete
program, albeit a simple one.
3) The user also gets a complete example they can copy, compile etc.
4) We can easily add extra examples as complete .cs files without
cluttering up the class overview page.

[By user here, I mean the person reading the docs]

> Also, 
> % ls gtk-sharp/doc/en/Gtk/*.cs
> gtk-sharp/doc/en/Gtk/Viewport1.cs

As you can see, I have only added one complete example so far. There is a lot of work to be done on this. 
Alejandro Sánchez Acosta is also creating examples in monkeyguide/samples/tutorial, which we can copy, and contribute to.

In short, I think class overviews should have 1 or 2 methods as an example, and we should create a 'samples' directory in each assembly's API doc directory, eg. doc/en/Gtk/samples

Does this sound sane to people?

At the moment, I don't think it's a critical priority because (last time I checked) the doc browser doesn't have any way to display/link complete examples.
But it will soon I'm sure. :)