Forum: Ruby Newbie question - gem documentation

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 Sampson_

Here is a source code https://github.com/kiyoka/fuzzy-string-match and
there are some sample code snippets. Do you check this
http://rubydoc.info/gems/fuzzy-string-match/0.9.4/ ?

2013/1/1 John Sampson <jrs.idx@ntlworld.com>:

On Tue, Jan 1, 2013 at 6:55 AM, John Sampson <jrs.idx@ntlworld.com> 
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.
https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance), from
that you can choose how much "fuzziness" to apply, which can be highly
domain-specific.

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.
> https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance), 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.

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

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 So Paulo, Brazil
Computer engineering
Embry-Riddle Aeronautical University, USA


2013/1/1 tamouse mailing lists <tamouse.lists@gmail.com>

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?

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:
https://github.com/kiyoka/fuzzy-string-match/blob/...

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:
https://github.com/kiyoka/fuzzy-string-match/issues


-----
Carlos Agarie

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


2013/1/1 John Sampson <jrs.idx@ntlworld.com>

On 01/01/2013 17:11, Carlos Agarie wrote:
>
> -----
> Carlos Agarie

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 Sampson_