Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

Re^2: Coming up with good examples in POD

by Lady_Aleena (Curate)
on Jul 28, 2020 at 06:01 UTC ( #11119882=note: print w/replies, xml ) Need Help??


in reply to Re: Coming up with good examples in POD
in thread Coming up with good examples in POD

I may be missing something, but how is POD not for breaking down the implementations of a module and using it successfully? When I go to read how to use a module I have not seen before, I read the documentation of it. I have never looked at a module's unit tests to figure out how to use any module. I also do not look at the code searching for comments on usage either. Most of the time when I use a module, I do not even look at its code. (The few times I have looked at modules' code, I could not understand it, even metaphorically standing on my head.)

One of my bigger problems using modules is that some make me play guessing games on how to use them. I have walked away from several modules because the documentation was lacking in examples of usage, or only showed the most common usages and ignored anything fringe. If I have to play guessing games when trying to use a module, I quit trying usually and roll my own code to get what I want.

So, when I write the documentation for my modules, I want to come up with all the usages I can imagine and note them so users can see the full capabilities of what my modules can do. I do not want potential users to play guessing games on how to use what I wrote. I also do not want potential users to have to go on a treasure hunt (looking at the code and tests), to see how to use the module either.

But as I said, I may be missing something.

My OS is Debian 10 (Buster); my perl versions are 5.28.1 local and 5.16.3 or 5.30.0 on web host depending on the shebang.

No matter how hysterical I get, my problems are not time sensitive. So, relax, have a cookie, and a very nice day!
Lady Aleena
  • Comment on Re^2: Coming up with good examples in POD

Replies are listed 'Best First'.
Re^3: Coming up with good examples in POD
by hippo (Chancellor) on Jul 28, 2020 at 09:22 UTC
    I may be missing something, but how is POD not for breaking down the implementations of a module and using it successfully? When I go to read how to use a module I have not seen before, I read the documentation of it.

    POD (and user-facing documentation in general) is for describing the purpose and usage of modules and their functions. It is not, in general cases, for describing the internal ways the module achieves its ends as these are very rarely any concern of the user.

    For each function/sub/method one could reasonably expect the documentation to include:

    • function name
    • Arguments: types, names/positions, optional/mandatory, defaults, acceptable values
    • Return values: types, names/positions, flag values
    • Conditions which will throw exceptions
    • Prose describing the purpose, side-effects, caveats, context-sensitive matters, etc.
    • Example(s) showing how to call the function with suitable arguments, etc.

    In other words, everything to do with the purpose of the call and the interface to it. Everything else internal to the function does not need documenting here (eg. private variables, other functions it calls, etc.).


    🦛

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (7)
As of 2020-09-29 10:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    If at first I donít succeed, I Ö










    Results (146 votes). Check out past polls.

    Notices?