Re: Mandatory -dbg packages for libraries? (and API docs too)
On Wed, Apr 25, 2007 at 04:23:38PM +0200, Stefano Zacchiroli wrote:
> On Tue, Apr 24, 2007 at 08:12:46AM -0700, Steve Langasek wrote:
> > > If we are talking about hand-written documentation you're of course
> > > right. However if you're talking about documentation which can be
> > > generated automatically from sources (and not that it was the "ideal"
> > > point of Neil) than you're not.
> > There are ways to generate manpages from --help output of programs. We
> > still have a lot of programs in Debian with no manpages.
> According to my experience with html2man doesn't work that properly
> every time, but I see your point. But still I don't get the objection:
> is the laziness of people a good reason not to state the "right" path?
Is this "right" path going to describe best practices for providing *good*
API documentation? Some maintainers will do anything policy (or lintian)
tells them to. If you say "libraries must include API documentation" in
policy, they'll write API documentation -- even if they don't know how to
write documentation or don't understand the API. Wrong API docs are surely
worse than not having no docs, aren't they?
> > > It happened to me many times to find library -dev packages with upstream
> > > sources commented with some literate programming stuff but nevertheless
> > > missing the corresponding automatically generated API docs in the
> > > package. That's a pity. And that's something the policy should address.
> > Hmm, I don't agree that it needs to be addressed in policy, FWIW.
> Fair enough, but note that having man pages is actually addressed by the
> policy. Why do you think API doc shouldn't? After all man pages are docs
> for users and API doc are too, with the only difference that in the
> latter case the "users" are programmers.
If I thought putting it in policy would significantly improve the
availability of API docs in Debian, I would support doing so. But I don't
think this will happen, and anyway if people want to campaign for improving
our API documentation they can do that in any number of ways without asking
for it to be put in policy first.
Cheers,
--
Steve Langasek Give me a lever long enough and a Free OS
Debian Developer to set it on, and I can move the world.
vorlon@debian.org http://www.debian.org/
Reply to: