Re: [Draft] Bits from the lintian maintainers
Jeremiah Foster <jeremiah@jeremiahfoster.com> writes:
> I've got a question regarding the various lintian modules. I'm a command
> line person and often use tools like perldoc to read the documentation
> that is in with code. Lintian does seem to use plain old documentation
> very much which I think is too bad. It is considered a perl best
> practice. I'm happy to add that type of pod to the modules and the
> scripts as I come across the need. Is that useful?
The newer Lintian modules (the stuff under lib/Lintian) should all have
POD documentation, hopefully -- if not, it's a bug. I never wrote
documentation for the modules in lib that haven't moved under Lintian
since normally the API of the older modules is dodgy and should be redone
as part of the namespace move to Lintian::*, so writing POD for the
previous API seemed like a waste.
The checks themselves do indeed not have POD. I usually think of POD more
as end-user documentation, so am not sure how helpful it would be, but if
people would find it so, it may be a good way to document the internals
more. (Although one should also think about what should instead be moved
into a module instead of documented in-place in the check scripts.)
> I'd also like to move the README.Developer from plain text to pod while
> it is still early. pod can get translated into markdown and Mediawiki
> markup as well as html.
That's probably a good idea, since among other things it would let us
generate an HTML version to stick on lintian.debian.org. I have Perl
scripts that do that for text documentation, but the results of converting
POD are usually a bit better.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: