[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
+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
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-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
Re: [DISCUSS] Enable javadoc check on Solr too
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-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
Re: [DISCUSS] Enable javadoc check on Solr too
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-h...@lucene.apache.org > > --**--**- > To unsubscribe, e-mail: > dev-unsubscribe@lucene.apache.**org > For additional commands, e-mail: dev-h...@lucene.apache.org > >
Re: [DISCUSS] Enable javadoc check on Solr too
...and surely working in a branch as suggested by Alan would be a good idea :-) Thanks Alan, Tommaso 2013/1/18 Tommaso Teofili > 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-h...@lucene.apache.org >> >> --**--**- >> To unsubscribe, e-mail: >> dev-unsubscribe@lucene.apache.**org >> For additional commands, e-mail: dev-h...@lucene.apache.org >> >> >