Re: DOCBOOK: Re: methodsynopsisinfo tag?

[Alex Russell <alex at netWindows dot org>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Norm, thanks for getting back to me.

On Monday 17 February 2003 03:44 pm, Norman Walsh wrote:
> | My question is this: is there a <methodsynopisinfo> tag or anything I
> | can use in it's place? I'm looking to provide some sort of long
> | description about my class methods and I'm wondering if I'm either
> | missing a tag or incorrectly using a the <methodsynopsis> tag.
>
> Can you show us an example of what you're trying to do?

Sure!

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/netwindows/netWindows/winScripts/netWindows.js?rev=1.101&content-type=text/vnd.viewcvs-markup

It's going to look kind of odd for a couple of reasons:

	1.) I'm trying to document some Object Oriented JavaScript, which doesn't 
conform to "normal" inheritance models (it uses something called 
prototype-based inheritance)
	2.) I'm using a commenting hack to allow us to "inline" our documentation 
with our code. In essence, we're trying to use DocBook in the 
literate-programming style. This means you'll need to scroll down a bit to 
see a methodsynopsis tag.

For those not inclined to follow the link, here's a short excerpt:

<!-- assume classsynopsis tag opened above and and oclass and 
classsynopsisinfo info tags provided... -->

	<methodsynopsis>
		<type>boolean</type>
		<methodname>addDeps</methodname>
 		<methodparam>string <parameter>path</parameter></methodparam>
	</methodsynopsis>

	<!-- this is the section I'd like in a methodsynopsisinfo tag -->
	<para>
		<methodname>__scripts__.addDeps()</methodname> is identical 
		to <methodname>__scripts__.require()</methodname>.
	</para>

<!-- ...class synopsis continues in this style and eventually terminates -->

The gist of what I'm trying to do is to provide long descriptions about the 
usage of methods in (or near) their methodsynopsis tags. Given that 
JavaScript doesn't enforce strict structure the way that C++ or Java do, I 
could convert things to use functionsynopsis tags instead, but it seems 
like something of a hack and would (IMO) take more stylesheet customozation 
to get output that correctly depicts the relationships I'm trying to 
document.

Thanks for any guidance you can provide.

- -- 
Alex Russell
alex@netWindows.org
alex@SecurePipe.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE+UBkpoV0dQ6uSmkYRAovzAKCCxjIim2NAPArumwbGivoektfEWwCeKzIf
d7DI6+fmaD5YLcJF3u0WGsg=
=CUll
-----END PGP SIGNATURE-----