I have a feeling we've sorta assumed some use cases for whatever Pod design we're advocating, so I thought I'd write down what I'd like to do with Pod. At this level, I don't care how it gets done, which model it uses, or anything else.
This isn't a fantasy wishlist of anything I think I might want. These are things that I've wanted for a couple years. I'm not trying to start an RFC process, but think about how to motivate some of the things we are debating. These are just use cases, not really feature requests: ======Pull out the docs for a single method.in a class I want perldoc -f for modules. That works for perlfunc because there is a simple structure to the file where all the =item represent a function (and similarly for perldoc -q and the perlfaq). I'm not thinking ahead to what the method docs would look like. If I had this I'd be happy just to get plain text. ======Know which class the Pod is in One of the failings of Pod::Coverage right now is that it assumes that there is only one class per file and the filename represents the class. This means I can't use Pod::Coverage or Test::Pod::Coverage when Ihave a design that doesn't do that (e.g. a convenience class that's private and only a screen long). I'd really like a Pod parser to know what class it is in, and which class the documentation belongs to. =======Per class documentation, not per file documentation Related to the one above, I'd like to have NAME, SYNOPSIS, etc. for each class, not just per file. Well, what I really want is the Smalltalk class and method browsers, but I know I'm not going to get those. It's a major missing feature from my perlbrowser tool (on CPAN). Part of that means, though, that if I want that docs for Foo::Bar which live in Foo.pm, then perldoc6 has to know how to find that class. That's a much larger issue than just the Pod format. If I put more than one class in a file, I'd like to be able to extract it's documentation separately. Of course, this leads to huger problems making it work, so I'm not holding my breath. It's more likely I'll have to live with separate files :) ========Private docs There's documentation for module users, and there is documentation for module developers. I'd like to document the private methods too, but without something to tell perldoc6 that you want the secret docs, you don't see them. The secret docs are for the people working inside the code of the class (creators, maintainers, whatever), and those docs are just like the user docs in structure.
