Require projects to have solid API docs

[Andrew Pennebaker <an...@gmail.com>]

In the future, could Apache Incubator require projects to maintain better
API documentation before graduation? In particular, Kafka has rather sparse
documentation in v0.8. The Javadocs appear to be randomly hosted on this or
that professor webpage, and no Kafka javadoc has documentation for
*both* Consumers
and Producers.

-- 
Cheers,
Andrew

Re: Require projects to have solid API docs

[Emmanuel Lécharny <el...@gmail.com>]

Le 11/10/15 17:59, Andrew Pennebaker a écrit :
> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.

I'm ok with this proposal, when we have checked that every TLP has a
decent API documentation...

Good luck with that ;-)

/me guilty as charged...


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: Require projects to have solid API docs

[Joe Stein <cr...@gmail.com>]

The Apache Kafka javadoc and scala doc are published with source and
binaries https://archive.apache.org/dist/kafka/0.8.2.2/ and they can be
generated from source.

There is no javadoc for both producer and consumer (yet but you can
generate from trunk for 0.9) because the new java consumer has been in
development with testing underway now. If you want to consume from Kafka
(as stable) using the project client you have to use the Scala consumer.

There is a lot of documentation especially around the API
http://kafka.apache.org/documentation.html#api with lots of good links if
any issues github PR are accepted now.

For more kafka questions feel free to reach out to the community
http://kafka.apache.org/contact.html.

Thanks!

~ Joe Stein


~ Joe Stein

On Sun, Oct 11, 2015 at 11:59 AM, Andrew Pennebaker <
andrew.pennebaker@gmail.com> wrote:

> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.
>
> --
> Cheers,
> Andrew
>

Re: Require projects to have solid API docs

[Mark Thomas <ma...@apache.org>]

On 11/10/2015 16:59, Andrew Pennebaker wrote:
> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.

No.

It is not the role of the incubator to assess the *quality* of the code
or any other release artefact.

Graduation from the incubator is based on the quality of the community.
This is because a good community can always (and usually does) turn
around bad code. Good code will never save a poor community.

If you have an issue with a project's release artefacts, open a bug
report. Better still, open a bug report and provide a patch/pull request
with a fix.

Mark

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org