Thomas Wittek wrote:
> I mean POD uses constructs like headlines, lists, blocks, italic etc.
> which all describe _how it looks like_ and not _what it is_.

I think Damian would take exception to that statement. He worked quite hard to make sure that POD describes _meaning_ rather than _appearance_. He even renamed B<> from "bold" to "basis", I<> from "italic" to "important", and U<> from "underline" to "unusual". All of those are fairly odd choices, with the possible exception of "important", but they were clearly made with an eye to backwards compatibility of POD while changing people's focus from how it looks to what it is.

> A head3 might be the headline of a method documentation as well as one
> introducing the contact information for the author of a module.
> The directive doesn't have much semantics.
> Other people might use head2 for documenting methods, what leads to a
> pretty inconsistent look of the documentation.

Well, I'd argue that head3 has plenty of semantics. It's a level-3 header. How that's rendered is decided elsewhere.

I think the issue is not that head3 is insufficiently semantic, it's just that you want something that's even more specific. And POD 6 was designed with exactly that kind of thing in mind. You can, according to the existing S26, say things like:

    =Method the method synopsis goes here....
    =begin Parameters
    =item foo is the fooiest parameter
    =item bar is the barstest parameter
    =end Parameters

Furthermore, the Perl parser actually *keeps* the POD chunks, so you can access all that information in the context of the Perl parse. Damian and Larry were clearly laying the groundwork for exactly the sort of javadoc-ish features you are asking for.

The supreme irony of life is that hardly anyone gets out of it alive.
--Robert A. Heinlein [Job: A Comedy of Justice]

Reply via email to