From: Gavin Sinclair <gsinclair@...>
Date: 2004-02-12T13:32:22+09:00
Subject: Re: Standard libraries

> Hi,
>
>> From: "Gavin Sinclair" <gsinclair@soyabean.com.au>
>> Sent: Thursday, February 12, 2004 12:41 PM
>
>> > RDoc style is a must?  I don't like documentation buried within a
>> source code (code duplication for me).
>>
>> RDoc is the standard way to document standard library files.  It's
>> only code duplication if you put code in the comments :)
>
> Anyway, duplication of something I don't like to see/maintain.

I'm still not sure what you think is being duplicated.


>> Still with 'soap', the SOAP module should have enough documentation to
>> show the user how to use it.  And they should get an idea of which
>> classes are important to them, and which ones are not.
>
> I added many samples to show "how to use it" but it could not be
> enough.  I thought I was going to write some simple document and
> import libs to ruby's CVS.  But I have no plan to write it inline
> to avoid the duplication.

If there is a document describing 'soap' somewhere on the Internet, then a
few comments above the SOAP module and a link to the document would be
sufficient for a user, wouldn't it?

> I think we should remove soap, wsdl and xsd modules if "complete"
> documentation is required.

I don't think so, given the above.  I have no plans/desires to clutter up
code if it's not beneficial.

But then again, are you maintaining ruby/lib/soap/* and 'soap4r'
separately?  I would prefer to see just one package, with unit tests,
samples, etc. rolled into the Ruby distribution.  But that's just a gut
feel, not based on experience or qualifications.

Cheers,
Gavin