These two (generalized Pod comments and C<is doc> are both better than
my suggestion. :) They require less typing, so documenting at a finer
granularity (e.g. object attributes) is easier. It would provide an
opportunity for very thorough auto-generated documentation as outlined
in Mark's 2007 post
In Perl 5 I hate having Pod interleaved with code, since it is usually
mostly /user/ documentation and so just gets in the way. Having normal
Pod elsewhere (at end-of-file or in a different file) and keeping API
Pod docs inline (and having tools which might merge the two into nice
HTML if desired) would be the best of both world.
As for "#={ Pod }" vs "is doc", since I've been working on Perl 6
highlighting in vim, the first difference that comes to mind is that
highlighting the #={ Pod } form like other Pod (with L<inks> looking
distinct n' all) is easier and makes more sense since it's not just a
normal string (which might have come from anywhere). Highlighting the
other form would be a special case that might be hard to detect, and
arguably shouldn't be, since it is just a string.
