Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic
 
PerlMonks  

How to read CPAN documentation

by perl.j (Pilgrim)
on Jul 06, 2012 at 11:55 UTC ( #980242=perlquestion: print w/ replies, xml ) Need Help??
perl.j has asked for the wisdom of the Perl Monks concerning the following question:

If you ask me, reading the documentation for everyday CPAN modules (as well as many others) is a hassle. They are usually written with the seasoned Perl programmer in mind. With that said, it can become very difficult to understand CPAN documentation if it isn't a tutorial or walkthrough.

For example, JSON.pm is an app that I will soon be using. The issue is, in my eyes, the documentation is poor. It gives you a bunch of functions and what they do, but it says nothing about how to do it, besides the synopsis, which really doesn't help much

So, my question to you is, how can I become better at reading CPAN module documentation, and understanding how to use modules that don't come with books or tutorials in them?

--perl.j

Comment on How to read CPAN documentation
Re: How to read CPAN documentation
by choroba (Abbot) on Jul 06, 2012 at 12:06 UTC
    Experiment, use Google, PerlMonks, StackOverflow, IRC channels... Once you understand the module, send patches to the author to improve the documentation.
Re: How to read CPAN documentation
by muba (Priest) on Jul 06, 2012 at 12:09 UTC

    How does it not help much? I mean this as a sincere question, not to sound harsh or critisizing. I'm just wondering which part is causing you troubles.

      I'm actually trying to send my JSON structure to Perl, and then have Perl send it to my DB. The problem is, I'm clueless, but that's a whole different thread.

      --perl.j

        Well, at least you understand the nature of the problem, which in my experience means you're 80% of the way to a solution. :-)

        Many CPAN modules are quite poorly documented (and I'm including my own here). They often do a good job of listing the functions/methods defined by the module, with a brief description of what each function does, its inputs, its output, etc (we mostly have Test::Pod::Coverage to thank for that; without its existence CPAN documentation would be a lot worse); and they're usually quite good for boilerplate sections such as "here is the link to report bugs".

        The places they fall down is documenting why you might want to use the module in the first place (I suppose the assumption is that if you're reading the documentation, you've already made that decision); and fully worked practical examples of the use of the module, especially showing how it interacts with other commonly used modules. (For example, JSON could document how to interact with JSON RESTful APIs over the web using LWP::UserAgent; or how to manage collections of JSON on the file system using Path::Class.)

        There are fairly obvious reasons for this. If you're writing a module because you just need to get a job done, then you're probably concentrating more on doing the job than documenting it. Or if you're writing a module for fun; then documenting it is likely to be the least fun part. (And of course there are plenty of people for whom English is not their primary language, who find writing documentation in English especially difficult.)

        One overlooked area of documentation is the project's test files. These are Perl scripts (but with a ".t" suffix instead of ".pl") which show the software's intended behaviour. Invest some time in learning how Test::More works, and it will pay dividends - you'll be able to dive into a module's test cases and use them as extra documentation!

        If you do have any ideas for documentation for a CPAN module, submit it (in pod format) to the project's bug tracker. In most cases the author will be very happy to accept it - documentation provided this way is documentation he/she does not need to write himself/herself! Especially that sort of documentation about how and why to use a module in real-life tasks, which is so often overlooked. In cases of very extensive documentation, maybe format it into a separate document from the main module documentation. (e.g. for module Foo::Bar, write a Foo::Bar::Cookbook, Foo::Bar::Tutorial or Foo::Bar::FAQ document.)

        There ought to perhaps be a project that looks at the top 100 most important (by whatever metric) distributions on CPAN; identifies what they are missing in documentation; and writes it! That is, we should do for documentation, what Phalanx already did for test suites.

        Update: I've expanded upon this post in perldoc plus plus.

        perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

        Send it to Perl how? Through CGI? Over a socket? From a file? To the script's STDIN? Those all require a slightly different approach, but generally you'll eventually end up with the whole JSON data in a variable, let's say $json. Then you use one of the JSON decoding mechanisms - I'd go for the first one in the synopsis that seems to match the description, so you'd have a line like $perl_data_structure = decode_json $json;.

        Now, what $perl_data_structure looks like depends on what the outermost element of the JSON data was. Was it a map? Then $perl_data_structure will be a hash ref. Was it an array? Then $perl_data_structure will be an array ref. I am assuming you know what sort of data you want to send to your script and what it's formatted like, so this shouldn't be too much of an obstacle.

        Inserting it into a database, again, can't happen without asking yourself some questions, first. What do the tables in the database look like? What tables are there, what columns do they have and what data types go into those columns? Which elements from the incoming data do I want to insert? How do I transform the data structure into SQL -- but note that at this point you're no longer dealing with JSON. All you have is just an ordinary complex Perl data structure.

Re: How to read CPAN documentation (code)
by toolic (Chancellor) on Jul 06, 2012 at 13:04 UTC
    After I read the documentation, I head straight for code examples.

    A good CPAN distribution will have several tests, conventionally in the t directory. For example, on the JSON page, follow the MANIFEST link. I see roughly 50 test files. In these files, there are examples of how functions and methods are called (specific values passed to those functions), and examples of what is returned from functions.

    Some CPAN distributions have examples directories ("eg", "bin" etc.) which consist of short command line utilities for using the modules.

    Look at the source code itself. Sometimes authors embed helpful comments.

    If you want more examples of usage, try a Super Search.

    If you start using a module, and you find the POD inadequate, please submit specific enhancements via RT. CPAN is not just a spectator sport; you can participate too. If you include a patch, that increases the chances of the documentation being improved, not just for you, but for the whole community. Even if the patch is not applied by the author, the RT report is visible to everyone.

      Never usually look in the files of the module. I just use 'em :-). Thanks for the advice! I'll try it.

      --perl.j
Re: How to read CPAN documentation
by zentara (Archbishop) on Jul 06, 2012 at 13:15 UTC
    I'm just a practical programmer, but this is what I do.

    Read the perldoc which comes with the module, then look thru the module's source tree for directories or files with names like examples, cookbook, test, etc. In there you often will find many usages.

    If those come up empty, I google for it, like google perl Json.pm and you will find code samples.

    Module authors don't want to clutter their perldocs with too much example code, as it makes it harder to scan thru quickly. Plus many of them don't write English very well anyways. :-)


    I'm not really a human, but I play one on earth.
    Old Perl Programmer Haiku ................... flash japh
Re: How to read CPAN documentation
by scorpio17 (Monsignor) on Jul 06, 2012 at 13:15 UTC

    Just use to_json() to go from perl to json, and from_json() to go from json to perl. Here's an example:

    use strict; use JSON; use Data::Dumper; # Here's some data my $data = { A => 1, B => "hello world", D => [ [ 'dog', 'cat', 'bird', ], [ 'red','green','blue'], ], D => { X => 1, Y => 2, } }; # print the data print Dumper($data), "\n"; # convert perl data to json, then print out the json my $json = to_json($data); print "$json\n"; # convert the json back to perl, then print it. # should be the same as before my $data2 = from_json($json); print Dumper($data2), "\n";
Re: How to read CPAN documentation
by Anonymous Monk on Jul 06, 2012 at 13:39 UTC

    The issue is, in my eyes, the documentation is poor.

    Poor how? Please stop reading now and write down how its poor, things you don't like, things that are missing, questions that are raised, questions that aren't answered.

    After you have a list of things reveal spoiler below

Re: How to read CPAN documentation
by bulk88 (Priest) on Jul 06, 2012 at 16:39 UTC
    If you need to look at the source code of a module, the author failed in writing their documentation. If Perl was C, it would be harder to not document your code since the parameters and return value can't be hidden. In Perl both are hidden. In writing docs, I basically address the following questions.
    • What are the parameters?
    • how many?
    • variable parameters?
    • what parameter validation is performed?
    • how is error condition indicated? die/exceptions? warn? $!? return value?
    • What is the return value? list or scalar?
    • what are the possible errors (if possible, sometimes they come from something your module calls)?
    • common ways to leak resources
    • common mistakes
    • does undef as a parameter have special meaning?
    • what the function DOES NOT do
    • alternatives in same module, other modules or perl language
    • if XS and wrapping a C lib, situations that create unavoidable crashes or bugs in the C lib you as the module author hit
Re: How to read CPAN documentation
by Kenosis (Priest) on Jul 06, 2012 at 16:56 UTC

    If I find a Perl module's documentation obscure (either it's 'sparse' or I am), I may google something like the following:

    "use Data::Dumper" examples

    Although I think the documentation for Data::Dumper is fine, I've encountered a lot of documentation that's not well written--in my opinion, of course.

    Writing good documentation is a skill that's separate and distinct from programming skills, and it requires that a programmer shift into being a teacher. Being a seasoned programmer doesn't mean being a good teacher.

Re: How to read CPAN documentation
by TomDLux (Vicar) on Jul 06, 2012 at 17:30 UTC

    I agree totally. I've ocassionally looked at a module with an interesting name, let's say Fnord.pm, but there's no reference to what Fnording is. There's an explanation of how to invoke routines, but no mention of why, of what problem this modeule's services will solve.

    As Occam said: Entia non sunt multiplicanda praeter necessitatem.

Re: How to read CPAN documentation
by davido (Archbishop) on Jul 06, 2012 at 18:57 UTC

    Don't forget that most modules have a test suite that can provide additional clues as to how a module may work. And some of the more complete distributions will contain an examples/ directory that contains some brief working examples. I wish more distributions did that.


    Dave

      Don't forget that most modules have a test suite that can provide additional clues as to how a module may work

      Test suites are supposed to be examples of usage ;)

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://980242]
Approved by muba
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (11)
As of 2014-07-30 12:11 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (231 votes), past polls