Re: policy suggestion: API docs are not for users
In message: <[🔎] 1041363880.2837.203.camel@pathfinderii.chu.cam.ac.uk>
Mark Howard <mh@tildemh.com> writes:
>Hi,
> I've just noticed that the user documentation package for ant (a tool,
>not a library) contains 15 MB of API references. I've since filed bug
>#174876 asking for this to be removed.
Sadly, having the API docs there is somewhat appropriate.
>If anyone has legitimate reasons for including API docs in a -doc
>package (for a program, not a library), then I would love to know what
>they are.
Ant is as much a framework as a tool; to get it to do what you want
(if what you want isn't something that the ant developers thought was
common or important), you frequently have to write helper classes
that get loaded into the ant tool, and which then act as additional
rule handlers. To write these helper classes, you need to know the
ant API.
I could say some uncomplimentary things about this design choice
for ant, but there's really no point. The result, though, is that
to properly get ant to do the right thing in many circumstances
(particularly when using it with machine-generated code, non-java
builds, or configuration), you have to extend ant via its API,
and this is explicitly condoned and encouraged behaviour for the
end-user.
Thus, the API is in the end-user docs, not just the developer docs.
I suppose that one could argue that anyone trying to use ant for
their own programs (instead of just using it as an incidental tool
for building someone else's program) should install an ant-dev package,
too... but that seems slightly strange to me, since the person is
still acting as an end-user for the tool, instead of incorporating
it into their program.
- Alex
Reply to: