Newbie question - gem documentation

Ruby
1

Hello -

I am trying to understand how to find out how to use a gem that I have
installed -
specifically fuzzy-string-match. I have not been able to find a
description - rdoc
etc. are as easy to read as Sanskrit - is there an introduction to these
mysteries
for the newcomer anywhere?

Regards

John S.

2

Here is a source code GitHub - kiyoka/fuzzy-string-match: fuzzy string matching library for ruby and
there are some sample code snippets. Do you check this
File: README — Documentation for fuzzy-string-match (0.9.4) ?

2013/1/1 John S. [email protected]:

3

On Tue, Jan 1, 2013 at 6:55 AM, John S. [email protected]
wrote:

I am trying to understand how to find out how to use a gem that I have
installed -
specifically fuzzy-string-match. I have not been able to find a description

  • rdoc
    etc. are as easy to read as Sanskrit - is there an introduction to these
    mysteries
    for the newcomer anywhere?

Is the issue that you don’t know how to call the methods (which the
documentation shows), or that you don’t know what and how to implement
a fuzzy search? The gem is giving you the means to calculate
“distance” between two strings (the algorithm is named “Jaro-Winkler”
which is the measure of similarity between two strings, c.f.
Jaro–Winkler distance - Wikipedia), from
that you can choose how much “fuzziness” to apply, which can be highly
domain-specific.

4

On Tue, Jan 1, 2013 at 8:29 AM, John S. [email protected]
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.

5

On 01/01/2013 14:04, tamouse mailing lists wrote:

a fuzzy search? The gem is giving you the means to calculate
“distance” between two strings (the algorithm is named “Jaro-Winkler”
which is the measure of similarity between two strings, c.f.
Jaro–Winkler distance - Wikipedia), from
that you can choose how much “fuzziness” to apply, which can be highly
domain-specific.

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.

All I have found so far are disjointed fragments of code and some
legalese. I only mention
fuzzy-string-match as an example. It might be easier for me to write my
own code based on
theoretical descriptions of matching algorithms.

6

On 01/01/2013 15:13, tamouse mailing lists wrote:

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.

So README.md is where one looks, and it is in the ‘repo’, whatever that
is. I see that
the method “.create” is a combination of “.new” and “.save” - What does
“.save” do?
For idle curiosity, what does “.md” mean? What are rdocs for? Are they
no longer
useful?

7

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

Control engineering
Polytechnic School, University of So Paulo, Brazil
Computer engineering
Embry-Riddle Aeronautical University, USA

2013/1/1 tamouse mailing lists [email protected]

8

A “repo” is a repository. It’s the place where your project is stored
via
git, e.g. the git repository of fuzzy-string-match is hosted by Github
and
is accessible via the URL
git://github.com/kiyoka/fuzzy-string-match.git.

“.md” is a format called Markdown, a plain text to HTML converter meant
for
web usage. It’s very simple and it’s used in lots of places (e.g.
Github,
Stackoverflow). You can read more about in this link:
http://daringfireball.net/projects/markdown/

Finally, the method create is used to generate an object that will do
the
work you need, at least this is what I get from reading the README:

If you have specific doubts about how to use this gem and/or want more
documentation (and you should), please create a free Github account and
open an issue in the issue tracker:

Carlos A.

Control engineering
Polytechnic School, University of So Paulo, Brazil
Computer engineering
Embry-Riddle Aeronautical University, USA

2013/1/1 John S. [email protected]

9

On 01/01/2013 17:11, Carlos A. wrote:

Carlos A.

Many thanks for these pointers, especially the last one. I see that
fuzzy-string-match has issues not fixed in the last nine months, so that
saves me
some time!

Regards

John S.