lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hoss Man (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (LUCENE-6257) Remove javadocs from releases (except for publishing)
Date Thu, 19 Feb 2015 22:09:12 GMT

    [ https://issues.apache.org/jira/browse/LUCENE-6257?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14328187#comment-14328187
] 

Hoss Man commented on LUCENE-6257:
----------------------------------

bq. I don't know of any other uses for the javadoc jar than in IDEs. 

the primary usage of javadoc jars pre-dates IDEs.  it's so people can download just the binary
libraries & javadocs and write their own code against the library w/o needing to read
the source (or build the javadocs from source) -- having a javadoc.jar with java is like getting
the \*.h files along with a \*.so ... you need that to know what methods you're allowed to
call.

(sure, we have the javadocs online -- but for the same reason not all applications are applets,
it's reasonable to want to download it and read offline)

* the primary argument i've seen in favor of _providing_ javadoc jars come from commercial
software (ie: we sell you a license to use this library in your application, but we won't
give you the original source).
* the primary arguments i've seen in favor of _consuming_ javadoc jars come from people who
want to be able to use a library "clean room" w/o any risk that anyone will say they ever
saw the original source code.

the former doesn't apply to us, i would normally think there's no reason the later should
apply to us (Virally licensed projects maybe, but not ASL) except that i have still seen/meet
people at big companies where they are not allowed to download or look at the *source* code
for open source projects because of the paranoia of their employeer in claiming ownership
of code their employees cut/pasted -- they can however freely download & use libraries
based on the license ... but in order to use those libraries, they need to be able to read
the javadocs and know what methods to call.

> Remove javadocs from releases (except for publishing)
> -----------------------------------------------------
>
>                 Key: LUCENE-6257
>                 URL: https://issues.apache.org/jira/browse/LUCENE-6257
>             Project: Lucene - Core
>          Issue Type: Improvement
>            Reporter: Ryan Ernst
>
> In LUCENE-6247, one idea discussed to decrease the size of release artifacts was to remove
javadocs from the binary release.  Anyone needing javadocs offline can download the source
distribution and generate the javadocs.
> I also think we should investigate removing javadocs jars from maven.  I did a quick
test, and getting the source in intellij seemed sufficient to show javadocs.   However, this
test was far from scientific, so if someone knows for sure whether a separate javadocs jar
is truly necessary, please say so.
> Regardless of the outcome of the two ideas above, we would continue building, validating
and making the javadocs available online.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message