From: Carlos Agarie Date: 2013-01-02T01:50:21+09:00 Subject: Re: Newbie question - gem documentation --90e6ba6e81d8d1524f04d23cece4 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable John, When you install a gem in your machine, you can use "gem server" and go to localhost:8808 to see its RDoc documentation in your browser. But I must agree with you that lots of gems have awful documentation - I lost count of how many times I had to read the code (ruby or C) to understand what was going on and how to use/extend it. That's a problem we should address. Unfortunately, this seems to be the case with fuzzy-string-match. There's no documentation except for the README - which is "fine" as its API is extremely simple (there's just one method to call). ----- Carlos Agarie Control engineering Polytechnic School, University of S=E3o Paulo, Brazil Computer engineering Embry-Riddle Aeronautical University, USA 2013/1/1 tamouse mailing lists > On Tue, Jan 1, 2013 at 8:29 AM, John Sampson wrote= : > > The issue is that I don't know how to read the documentation. Where, or > how, > > does it show how to > > call the methods? I would have thought there would be a general > description > > somewhere explaining > > the structure of Github or Gem documentation. > > Github is way beyond the scope of a single gem to describe. > > The README.md file in the repo pointed at by Mateusz shows how to make > the calls in the Sample Code section. > > If the README.md file had been written as a README.rdoc, it would have > been included in the gem rdocs. That doesn't seem to be much in > practice any more as most people go to Github to find gems. Not sure > what to do about it. > > --90e6ba6e81d8d1524f04d23cece4 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
John,

When you install a gem in you= r machine, you can use "gem server" and go to localhost:8808 to s= ee its RDoc documentation in your browser.

But I must agr= ee with you that lots of gems have awful documentation - I lost count of ho= w many times I had to read the code (ruby or C) to understand what was goin= g on and how to use/extend it. That's a problem we should address.

Unfortunately, this seems to be the case with fuzzy-string-m= atch. There's no documentation except for the README - which is "f= ine" as its API is extremely simple (there's just one method to ca= ll).


-----
Carlos Agarie

Control engineering
Polyte= chnic School,=A0University of S=E3o Paulo, Brazil
Computer engine= ering
Embry-Riddle Aeronautical University, USA


2013/1/1 tamouse mailing lists <t= amouse.lists@gmail.com>
On Tue, Jan 1, 2013 at 8:29 AM, John Sampson <jrs.idx@ntlworld.com> wrote:
> The issue is that I don't know how to read the documentation. Wher= e, or how,
> does it show how to
> call the methods? I would have thought there would be a general descri= ption
> somewhere explaining
> the structure of Github or Gem documentation.

Github is way beyond the scope of a single gem to describe.

The README.md file in the repo pointed at by Mateusz shows how to make
the calls in the Sample Code section.

If the README.md file had been written as a README.rdoc, it would have
been included in the gem rdocs. That doesn't seem to be much in
practice any more as most people go to Github to find gems. Not sure
what to do about it.


--90e6ba6e81d8d1524f04d23cece4--