Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Re: Re: Inline POD vs. EOF POD

by clemburg (Curate)
on Jul 10, 2001 at 19:25 UTC ( #95326=note: print w/ replies, xml ) Need Help??


in reply to Re: Inline POD vs. EOF POD
in thread Inline POD vs. EOF POD

There are modules that are intended for users that are developers, and these may need very detailed technical documentation, or even documentation about the implementation of certain features.

In my personal experience with Perl, I'd say to these people: read the code now, you will, anyway.

In general, I think POD syntax is the problem here, not the idea of "inline" vs. "EOF" documentation. If POD syntax would waste less screenspace, everybody would use "inline" POD for implementation-level documentation.

Christian Lemburg
Brainbench MVP for Perl
http://www.brainbench.com


Comment on Re: Re: Inline POD vs. EOF POD
Re: Inline POD vs. EOF POD
by Abigail (Deacon) on Jul 11, 2001 at 03:01 UTC
    There are modules that are intended for users that are developers, and these may need very detailed technical documentation, or even documentation about the implementation of certain features.

    I doubt that very much. Except for use in a classroom, modules are written to be used. Even if the users are developers. Not to be picked apart and their implementation studied. gdb wasn't written so people could study its implementation, was it? Sure, some people using a module will maintain it. But it's only for hardly used modules were maintainers are a significant number.

    In general, I think POD syntax is the problem here, not the idea of "inline" vs. "EOF" documentation. If POD syntax would waste less screenspace, everybody would use "inline" POD for implementation-level documentation.

    Well, that's quite opposite of one of my reason not to use inline POD. Changing the syntax of POD to use less screenspace doesn't solve the problem of having the documentation in the same order as the subroutines. What makes you think noone will bother about order of documentation as soon as POD stops wasting screenspace?

    -- Abigail

      I doubt that very much. Except for use in a classroom, modules are written to be used. Even if the users are developers. Not to be picked apart and their implementation studied.

      When it comes to the traditional CPAN module, I'm with you all the way.

      But there are other cases; consider the in-house developed program consisting of a number of classes. This is often not a case of just using a stable module or two, but a living piece of code that is indeed being changed, added to, refactored, reimplemented every once in a while.

      That was primarily what I was thinking of when stating that inline POD is useful to document interfaces. Not in a "guide" way, but in a "reference" way. If a class needs notes about intention, recommended use, etc. that should of course be part of the docs too.

      /J

        Now you are describing a very specific situation, which is a far cry from your earlier "everyone will use inline POD if the syntax gets changed". But even in this situation, what advantage will POD give you over (block) comments? After all, when you see the formatted POD, you no longer see the code, and I would think that people maintaining the code would like to see the code.

        -- Abigail

        Now you are describing a very specific situation, which is a far cry from your earlier "everyone will use inline POD if the syntax gets changed".

        I don't think it was me saying that, but never mind.

        The "specific situation" is one that I encounter every day: I author and maintain a number of programs/applications written in Perl. I put common stuff into general CPAN-style modules, but the actual program functionality is always a number of very domain specific classes whose interface needs to be documented. For that I use POD which I think works fine, especially since I also use a POD/module browser that will jump me right into the source when I need that.

        Writing CPAN modules is another "specific sitation", although a more common one for some people.

        Again -- the interface needs to be documented, the usage too. The interface should be documented near the implementation, hence inline POD. The usage should be described and explained. EOF or BOF POD is perhaps more natural in this case.

        The issue of where to place POD (if that's what you like best) is maybe not "either-or", rather "both", since both are needed.

        New revised personal preference :)

        • Usage: POD
        • Interface: Inline POD
        • Implementation: Perl Comment

        /J

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (6)
As of 2014-12-25 22:51 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (163 votes), past polls