>I sense that there is an underlying reason for the objection to writing >JavaDoc ;-) Do you really *want* URLs to Sun's website, or do you think >that writing the doc will be too much effort, or ... ? How about >writing it in multiple languages if that's where our skills are?
The underlying reason is that I think we doubtfully will be able to provide better Javadoc for the *whole* implementation then the official spec. But we will be able to describe our implementation specific things when the official spec is ambiguous or allows different behaviors. And that would the value of our docs. BTW who is the target reader of our JavaDoc? If it is a developer who uses JavaDoc as an API reference then what would be the motivation for him to use our Javadoc instead of the official spec? I think Classpath is a little bit different story. It is not a Java(tm) so a developer who writes for Classpath has to validate with Classpath docs whether his code is going to work. Thanks, Mikhail Loenko Intel Middleware Products Division >-----Original Message----- >From: Tim Ellison [mailto:[EMAIL PROTECTED] >Sent: Friday, January 13, 2006 4:39 PM >To: harmony-dev@incubator.apache.org >Subject: Re: Writing JavaDoc > >Loenko, Mikhail Y wrote: >> Well, I'll try to summarize what we have >> >> There are three types of methods: >> 1. Methods that are part of the API, they are specified, they follow the >> Sun's spec and we have nothing to add. >> 2. Methods that are part of the API and we have something to add (ex.: >> the spec allows multiple behaviors). >> 3. Private methods or methods in com.*, org.* areas etc. >> >> I think we all agree that we have to document #3. > >I agree it is good practice to document the implementation of some >non-API code for developers. That documentation may or may not be >JavaDoc. For example, many people typically don't do a full JavaDoc >comment for a private method. > >> But it's not clear for >> me what we do with #1 and #2. I suggest discussing #1 first. >> >> We might want to omit documentation for #1 methods (though if the doc >> describes all the methods except a single one - it might be confusing) > >Yes, that would be confusing. > >> or put there some standard words (like this method is implemented >> according to the spec) and either do or don't provide a link to the >> Sun's spec. >> In the .java source files we might either skip javadoc comment (though >> it would not improve code readability) or provide some standard words >> for all such methods. >> >> Another option is to put reworded content of Sun's spec into the >> documentation. I do not like this idea: if we say that our >> implementation works according to our wording but not to the official >> spec we might have problems with naming it Java (or we will have to say >> "we implement our own spec that is semantically equivalent to Sun's >> spec", which we'll have to prove first :). > >There is only one way that you can call an implementation Java(tm) -- >and that is to pass the JCK. > >> Moreover, we will need a >> number of native English speakers who will volunteer to write the docs >> for us. > >I sense that there is an underlying reason for the objection to writing >JavaDoc ;-) Do you really *want* URLs to Sun's website, or do you think >that writing the doc will be too much effort, or ... ? How about >writing it in multiple languages if that's where our skills are? > >AFAIK other projects that are implementing JSRs etc write the code and >documentation to go alongside it rather than link to the reference. >Perhaps our friends involved with Classpath can give us an insight as to >whether they regret writing JavaDoc, or whether they see it as a >valuable part of the effort (assuming that they have written all the doc!). > >> So, what do we do with the methods that act exactly as specified? > >My view is that we document them using our own words, and go for quality >documentation as well as quality implementation. > >Regards, >Tim > > >>>-----Original Message----- >>>From: Tim Ellison [mailto:[EMAIL PROTECTED] >>>Sent: Tuesday, January 10, 2006 7:21 PM >>>To: harmony-dev@incubator.apache.org >>>Subject: Re: Writing JavaDoc >>> >>>Sorry, I misunderstood. So your option #3 is not copying the JavaDoc >>>and redistributing it, but documenting links to the Sun site. >>> >>>IMHO, creating a set of JavaDoc that contains links to Sun's existing >>>JavaDoc is unlikely to appeal to most people -- the package/type/method >>>naming is enough of an index to go and find it easily on the Sun >> >> website >> >>>already. Publishing an index of links doesn't add anything. >>> >>>If the additional 'value' are the comments that are added, then I >> >> expect >> >>>that annotating Sun's original JavaDoc may be frowned upon(*). At >> >> least >> >>>if we originally author all the documentation we can do what we like. >>> >>>I'm interested to hear others' views. >>> >>>(*) you may recall the brouhaha over JDocs a while ago (if not, google >>>for 'Rick Ross JDocs' to get a flavour) >>> >>>Regards, >>>Tim >>> >>> >>>Loenko, Mikhail Y wrote: >>> >>>>Agreed with #1 >>>> >>>>Let me better explain #3. It is not a taglet copying Sun's spec. >> >> Instead >> >>>>it should insert pointers to specification of actual methods on Sun's >>>>website. So the resulting docs would look like the following: >>>> >>>> public Foo(type arg) >>>> >>>> Spec reference: See corresponding <a [link to Sun's spec]>J2SE >> >> API >> >>>>specification reference</a> >>>> >>>> And some additions, like "The spec allows this and that behavior, >> >> we >> >>>>did it this way because ..." >>>> >>>>What IMHO would not be a good idea is rewording complex method >>>>descriptions as we could unintentionally change semantics and mislead >>>>people who read our docs rather then official spec. >>>> >>>>Thanks, >>>>Mikhail Loenko >>>>Intel Middleware Products Division >>>> >>>> >>>> >>>>>-----Original Message----- >>>>>From: Tim Ellison [mailto:[EMAIL PROTECTED] >>>>>Sent: Tuesday, January 10, 2006 4:26 PM >>>>>To: harmony-dev@incubator.apache.org >>>>>Subject: Writing JavaDoc (was: Re: [RESULT] ( Was Re: [VOTE] Accept >>>> >>>>JIRA contribution HARMONY-16 >>>> >>>> >>>>>(Intel's contrib of security code for classlib))) >>>>> >>>>>Loenko, Mikhail Y wrote: >>>>> >>>>> >>>>>>Thanks for accepting the contribution >>>>>> >>>>>> >>>>>> >>>>>> >>>>>>>There's a bit of things that come out of this, like the >>>>>>>"com.intel.drl.spec_ref" javadoc tag that we should convert, and >>>> >>>>such. >>>> >>>> >>>>>>What would be the best for those javadocs? We can have 3 possible >>>>>>options: >>>>>>1. Copy-paste from the spec. Not sure it is legal >>>>> >>>>>This one definitely has to be out. The Sun JavaDoc is a >>>>>copyrighted/licensed work so making a verbatim copy is unacceptable. >>>>> >>>>> >>>>> >>>>>>2. Reword the spec. More likely to be legal >>>>> >>>>>As I see it, the JavaDoc fulfils (at least) two purposes. It >> >> embodies >> >>>>>the java spec (i.e. the definition of the standard library's >>>> >>>>behaviour), >>>> >>>> >>>>>and it is the principal developer documentation (i.e. how to use the >>>>>library). We do not want to change the specification in any way, but >>>>>can enhance the usability of the documentation to developers. >>>>> >>>>>For example, it would IMHO be wrong to specify the behaviour of a >>>> >>>>method >>>> >>>> >>>>>with more/less restrictions than the original reference javadoc, >>>> >>>>because >>>> >>>> >>>>>that implies that developers can make assumptions on one >> >> implementation >> >>>>>that they cannot on the other. However, it is reasonable to give >> >> more >> >>>>>examples, usecases, even performance, threading guidelines, etc. that >>>> >>>>do >>>> >>>> >>>>>not change the functional specification. >>>>> >>>>>So I'd say writing some JavaDoc, that was neither a direct copy of >> >> the >> >>>>>original, nor 'enhancing' the specification, can provide value to >>>>>developers. >>>>> >>>>> >>>>> >>>>>>3. Replace the tag with a different one and provide taglet to build >>>> >>>>the >>>> >>>> >>>>>>doc from the Harmony sources and Sun's spec. >>>>> >>>>>If I understand this correctly, then I don't see how this is >>>>>substantially different to option (1)? Whether it is a human that >> >> does >> >>>>>the cut-n-paste into the Harmony release, or a doclet, the result >>>>>includes somebody else's work. >>>>> >>>>>Regards, >>>>>Tim >>>>> >>>>> >>>>> >>>>>>Currently IBM's contribution seems to have #2. Does anyone have an >>>>>>opinion? >>>>>> >>>>>>Thanks, >>>>>>Mikhail Loenko >>>>>>Intel Middleware Products Division >>>>>> >>>>>> >>>>>> >>>>>> >>>>>>>-----Original Message----- >>>>>>>From: Geir Magnusson Jr [mailto:[EMAIL PROTECTED] >>>>>>>Sent: Friday, December 30, 2005 10:48 PM >>>>>>>To: harmony-dev@incubator.apache.org >>>>>>>Subject: Re: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution >>>>>> >>>>>>HARMONY-16 (Intel's contrib of >>>>>> >>>>>> >>>>>> >>>>>>>security code for classlib)) >>>>>>> >>>>>>> >>>>>>> >>>>>>>Tim Ellison wrote: >>>>>>> >>>>>>> >>>>>>> >>>>>>>>Geir Magnusson Jr. wrote: >>>>>>>><snip> >>>>>>>> >>>>>>>>>I'll finish moving to SVN and we'll put into the classlib tree, I >>>>>> >>>>>>suppose. >>>>>> >>>>>> >>>>>> >>>>>>>>Great. Thanks again Mikhail and the team! >>>>>>>> >>>>>>>>I suggest you either put it into the classlib tree at >>>>>>>>"classlib/java-src/security2" or leave it in the sandbox, then we >>>> >>>>can >>>> >>>> >>>>>>>>merge it into the existing security structure without breaking the >>>>>> >>>>>>world. >>>>>> >>>>>> >>>>>> >>>>>>>I'll go for the former and try to whip it into common shape, and we >>>> >>>>can >>>> >>>> >>>>>>>then decide how we do this - drop the existing security if >> >> security2 >> >>>>is >>>> >>>> >>>>>>>a superset, or merge. >>>>>>> >>>>>>>There's a bit of things that come out of this, like the >>>>>>>"com.intel.drl.spec_ref" javadoc tag that we should convert, and >>>> >>>>such. >>>> >>>> >>>>>>>Also will give me a good change to frame out the test infra. >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>>>Regards, >>>>>>>>Tim >>>>>>>> >>>>>> >>>>>> >>>>>-- >>>>> >>>>>Tim Ellison ([EMAIL PROTECTED]) >>>>>IBM Java technology centre, UK. >>>> >>>> >>>-- >>> >>>Tim Ellison ([EMAIL PROTECTED]) >>>IBM Java technology centre, UK. >> >> > >-- > >Tim Ellison ([EMAIL PROTECTED]) >IBM Java technology centre, UK.
