You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Tommaso Teofili <to...@gmail.com> on 2013/01/17 17:44:32 UTC
[DISCUSS] Enable javadoc check on Solr too
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
Re: [DISCUSS] Enable javadoc check on Solr too
Posted by Tommaso Teofili <to...@gmail.com>.
...and surely working in a branch as suggested by Alan would be a good idea
:-)
Thanks Alan,
Tommaso
2013/1/18 Tommaso Teofili <to...@gmail.com>
> 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 <ja...@basetechnology.com>
>
>> 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
>> <to...@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
>>> 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<de...@lucene.apache.org>
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>> ------------------------------**------------------------------**---------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.**org<de...@lucene.apache.org>
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>
Re: [DISCUSS] Enable javadoc check on Solr too
Posted by Tommaso Teofili <to...@gmail.com>.
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 <ja...@basetechnology.com>
> 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
> <to...@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
>> 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<de...@lucene.apache.org>
> For additional commands, e-mail: dev-help@lucene.apache.org
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.**org<de...@lucene.apache.org>
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
Re: [DISCUSS] Enable javadoc check on Solr too
Posted by Jack Krupansky <ja...@basetechnology.com>.
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
<to...@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
> 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
Re: [DISCUSS] Enable javadoc check on Solr too
Posted by Yonik Seeley <yo...@lucidworks.com>.
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
<to...@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 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
Re: [DISCUSS] Enable javadoc check on Solr too
Posted by Alan Woodward <al...@flax.co.uk>.
+1, this is an excellent idea, and I'm fully up for helping. There are a *lot* of missing docs, though - it might be worth making a branch first, just so that several people can hack on it before we let Jenkins loose.
Alan Woodward
www.flax.co.uk
On 17 Jan 2013, at 16:44, 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