Return-Path: X-Original-To: apmail-lucene-dev-archive@www.apache.org Delivered-To: apmail-lucene-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 17B48DB98 for ; Fri, 18 Jan 2013 07:25:14 +0000 (UTC) Received: (qmail 50932 invoked by uid 500); 18 Jan 2013 07:25:12 -0000 Delivered-To: apmail-lucene-dev-archive@lucene.apache.org Received: (qmail 50506 invoked by uid 500); 18 Jan 2013 07:25:07 -0000 Mailing-List: contact dev-help@lucene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@lucene.apache.org Delivered-To: mailing list dev@lucene.apache.org Received: (qmail 49630 invoked by uid 99); 18 Jan 2013 07:25:06 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 Jan 2013 07:25:06 +0000 X-ASF-Spam-Status: No, hits=1.5 required=5.0 tests=HTML_MESSAGE,RCVD_IN_DNSWL_LOW,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of tommaso.teofili@gmail.com designates 209.85.160.48 as permitted sender) Received: from [209.85.160.48] (HELO mail-pb0-f48.google.com) (209.85.160.48) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 Jan 2013 07:25:01 +0000 Received: by mail-pb0-f48.google.com with SMTP id wy12so515682pbc.21 for ; Thu, 17 Jan 2013 23:24:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:mime-version:in-reply-to:references:from:date:message-id :subject:to:content-type; bh=b2XwzJbyEp4bzUBdefCGqKPvbfo/Fvy1fdlJ6g4kPOo=; b=TmWpnCyAf06UCYJW9RTY1WEEOu6An+4dNQmPXxu5RbuxqrHw1Gdmih2F4yJw39x+ID luvdDVHVRaGNnn0spJ4TofAsSkbtxCHn1AkxhVqMIDMoUPuSQreZMvaBDFdCwfeMlKoH 99ltFDzcSTF2oZjvgLI5ke162Zq7MuBWzUfMXxbmatwqsBncsrjyzwS2Jpg21ljbr65k Qtkyc9+DVs7ULI4eWO0yPlLuvHqOVR6Hj0xfGPcgG4SIYbvC1CxdTUYH93Yy+u8QMfwC ZHRTeI6qO8WcWRsry6cu5mXwQWx9oEKZQRGMU5wRuUblU58e/qoWMSIZ3w9cxExHqtA3 2ROQ== X-Received: by 10.68.236.97 with SMTP id ut1mr2456761pbc.164.1358493880987; Thu, 17 Jan 2013 23:24:40 -0800 (PST) MIME-Version: 1.0 Received: by 10.68.24.136 with HTTP; Thu, 17 Jan 2013 23:24:00 -0800 (PST) In-Reply-To: References: From: Tommaso Teofili Date: Fri, 18 Jan 2013 08:24:00 +0100 Message-ID: Subject: Re: [DISCUSS] Enable javadoc check on Solr too To: dev@lucene.apache.org Content-Type: multipart/alternative; boundary=047d7b33d94e34b0ca04d38b018c X-Virus-Checked: Checked by ClamAV on apache.org --047d7b33d94e34b0ca04d38b018c Content-Type: text/plain; charset=ISO-8859-1 I see Yonik and Jack's points which look reasonable, but, at least for my experience, even if Solr is meant to be a "server" it often happens that developers (not necessarily plugins' developers) have to go deep into the code in order to understand how actually things work under the hood / fix bugs / etc. and I think that would really help. Also that should help our users feel more comfortable while browsing the Solr code which I think is important. Wrapping up I think introducing such check couldn't harm but just improve the overall quality of the project so I think it'd be worth the effort. My 2 cents, Tommaso 2013/1/18 Jack Krupansky > To the degree that people are using Solr merely as a server, that's fine. > I think the main issue are the "touch points" of Solr that relate to > user-developed plugins. The parts of Solr that invoke user plugins and that > user plugins invoke should have "Grade A Prime" Javadoc, if for no other > reason than that Eclipse is a friendly environment for developing and > testing plugins. > > -- Jack Krupansky > > -----Original Message----- From: Yonik Seeley > Sent: Thursday, January 17, 2013 12:42 PM > To: dev@lucene.apache.org > Subject: Re: [DISCUSS] Enable javadoc check on Solr too > > > Solr is in a different scenario though - the primary use case is to > run as a server. The majority of the java code is implementation to > support that. I personally don't refer to javadoc (by itself) during > development - so normal comments work just as well. Documentation of > methods should be on an as-needed basis, not mandated everywhere. > > -Yonik > http://lucidworks.com > > On Thu, Jan 17, 2013 at 11:44 AM, Tommaso Teofili > wrote: > >> Hi all, >> >> What do you think about (re) enabling javadoc check for Solr build too? >> At start it may be a little annoying (since a lot of Solr code misses >> proper >> javadoc thus we may have lots of failing builds) but that should turn in >> being a very useful thing for devs once that's fixed and we keep adding >> javadocs along with checked in code. >> >> So basically that should just use current Lucene's task for checking >> javadoc >> and make the build fail if there's any missing javadoc. >> We could add that as soon as 4.1 is out. >> >> What do you think? >> Regards, >> Tommaso >> > > ------------------------------**------------------------------**--------- > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.**org > For additional commands, e-mail: dev-help@lucene.apache.org > > ------------------------------**------------------------------**--------- > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.**org > For additional commands, e-mail: dev-help@lucene.apache.org > > --047d7b33d94e34b0ca04d38b018c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
I see Yonik and Jack's points which look reasonable, b= ut, at least for my experience, even if Solr is meant to be a "server&= quot; it often happens that developers (not necessarily plugins' develo= pers) have to go deep into the code in order to understand how actually thi= ngs work under the hood / fix bugs / etc. and I think that would really hel= p.
Also that should help our users feel more comfortable while browsing the So= lr code which I think is important.
Wrapping up I think intro= ducing such check couldn't harm but just improve the overall quality of= the project so I think it'd be worth the effort.

My 2 cents,
Tommaso


201= 3/1/18 Jack Krupansky <jack@basetechnology.com>
To the degree that people are using Solr mer= ely as a server, that's fine. I think the main issue are the "touc= h points" of Solr that relate to user-developed plugins. The parts of = Solr that invoke user plugins and that user plugins invoke should have &quo= t;Grade A Prime" Javadoc, if for no other reason than that Eclipse is = a friendly environment for developing and testing plugins.

-- Jack Krupansky

-----Original Message----- From: Yonik Seeley
Sent: Thursday, January 17, 2013 12:42 PM
To: dev@lucene.a= pache.org
Subject: Re: [DISCUSS] Enable javadoc check on Solr too


Solr is in a different scenario though - the primary use case is to
run as a server. =A0 The majority of the java code is implementation to
support that. =A0I personally don't refer to javadoc (by itself) during=
development - so normal comments work just as well. =A0Documentation of
methods should be on an as-needed basis, not mandated everywhere.

-Yonik
http://lucidworks.com

On Thu, Jan 17, 2013 at 11:44 AM, Tommaso Teofili
<tommaso.= teofili@gmail.com> wrote:
Hi all,

What do you think about (re) enabling javadoc check for Solr build too?
At start it may be a little annoying (since a lot of Solr code misses prope= r
javadoc thus we may have lots of failing builds) but that should turn in being a very useful thing for devs once that's fixed and we keep adding=
javadocs along with checked in code.

So basically that should just use current Lucene's task for checking ja= vadoc
and make the build fail if there's any missing javadoc.
We could add that as soon as 4.1 is out.

What do you think?
Regards,
Tommaso

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

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


--047d7b33d94e34b0ca04d38b018c--