http://www.perlmonks.org?node_id=980246


in reply to How to read CPAN documentation

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.

The synopsis pretty much gives you what you need, only you need to fill in the blanks. And there are plenty of blanks, which the module's documentation authour couldn't know. For example, what are you trying to do? Do you need to read JSON data and have it converted to a native Perl data structure? Or do you have a Perl data structure which you need serialized into JSON? Whatever the case, the following blanks to be filled in is: what will the source data look like? How will you obtain it? Is the source data in exactly the same format as you want your output to be, or do you need to switch around bits and pieces? Which? How? Why?

All of these questions are out of scope for the JSON docs.

For example, do you want to read in the ID3 tags of all MP3 files in a given directory, and store all metadata for all songs in one big JSON file? You can do that, but you will have to figure out how to pull the ID3 tags from the MP3s and in which structure you want to store everything.

Are you querying a webservice, which will respond with a one megabyte long string of JSON data, of which you need to extract one specific element, but where there is a complicated set of logical rules to determine where that element lives inside the structure? The JSON will make that a lot easier for you, by giving you one function call to convert the JSON to a data structure that's convenient to work with in the Perl language. But determining which element you want to get, and actually getting it? That's still up to you.

So, I ask again, what part is it that you don't understand?

Replies are listed 'Best First'.
Re^2: How to read CPAN documentation
by perl.j (Pilgrim) on Jul 06, 2012 at 12:12 UTC

    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
[reply]

      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'
[reply]
[reply]
        ... and then, for OP's next career (or retirement), you can use the knowledge and skills that will take a major part of your lifetime to absorb to write the kind of sketchy documentation that only another long term, hard-core, CS-degree-holding, uber-geek can decipher.

        AnonyMonk's observation about reducing your need for the docs, "on a daily/weekly/monthly basis", could be read (admittedly, not as AM intended ) to suggest that there's a substantial amount of time required just to learn to read the docs en route to so mastering their content as to make them unnecessary.

        Sorry, while I agree that most of the links can be useful... and are responsive -- in a fashion -- to OP's original question, they set the price of learning the answer too high, IMO, for a learner with a specific project in hand.

        Here in the Monastery there have been several interesting discussions (for example, Re: A reasonable approach to getting a Perl skill foundation?) of aspects of this problem -- some from the POV of the developer, like the one cited, and some from the perspective of the learner ( check with Super Search ) and not a few that may seem merely tangential at first (cf: Re: The sourcecode *is* the documentation, isn't it? and 3 or 4 followups thereto).

[reply]

      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.

[reply]
[d/l]
[select]

In Section Seekers of Perl Wisdom