harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: Android Javadocs
Date Fri, 17 Apr 2009 07:55:24 GMT
Yep, receiving contributions that improve the javadoc is just as
interesting as code improvements IMHO.

The contributions guidelines are the same too, i.e. we would want some
assurances that the documentation is not derived from anyone else's
work, or if they are derived you have their permission to contribute.

Of course, simply reading somebody else's javadoc does not then require
their permission to write your own text describing the same thing (i.e.
usual copyright rules apply).

Regards,
Tim

Nathan Beyer wrote:
> Improved javadoc sounds good to me.
> 
> IANAL, but I believe that the javadoc follows the same contribution
> rules as the source, so as long as the source changes can be
> contributed, so can the javadoc changes.
> 
> -Nathan
> 
> On Thu, Apr 16, 2009 at 8:05 PM, Jesse Wilson <jessewilson@google.com> wrote:
>> Hi!
>> I'm a developer on the Android core libraries, many of which are derived
>> from Harmony. In October, Android Dan Bornstein
>> said<http://markmail.org/message/7o2w7asiftn7o3dl> that
>> "A Day Of Reckoning would someday come", where we reintegrate Android and
>> Harmony sources. I'm working on that effort.
>>
>> One major difference between Harmony and Android is the Javadocs. We've
>> written lots. For example, here's our docs on
>> java.util.regex.Pattern<http://developer.android.com/reference/java/util/regex/Pattern.html>
>> ,
>>
>> Represents a pattern used for matching, searching, or replacing strings.
>> Patterns are specified in terms of regular expressions and compiled using an
>> instance of this class. They are then used in conjunction with a
>> Matcher<http://developer.android.com/reference/java/util/regex/Matcher.html>
>> to
>> perform the actual search.
>>
>> A typical use case looks like this:
>>
>>
>>  Pattern p = Pattern.compile("Hello, A[a-z]*!");
>>
>>  Matcher m = p.matcher("Hello, Android!");
>>  boolean b1 = m.matches(); // true
>>
>>  m.setInput("Hello, Robot!");
>>  boolean b2 = m.matches(); // false
>>
>>
>> The above code could also be written in a more compact fashion, though this
>> variant is less efficient, since Pattern and Matcher objects are created on
>> the fly instead of being reused. fashion:
>>
>>
>>     boolean b1 = Pattern.matches("Hello, A[a-z]*!", "Hello, Android!"); // true
>>     boolean b2 = Pattern.matches("Hello, A[a-z]*!", "Hello, Robot!");
>>  // false
>>
>>
>> Please consult the package
>> documentation<http://developer.android.com/reference/java/util/regex/package.html>
>> for
>> an overview of the regular expression syntax used in this class as well as
>> Android-specific implementation details.
>>
>> Harmony's docs are comparatively
>> sparse<http://www.jdocs.com/harmony/5.M5/java/util/regex/Pattern.html>
>> :
>>
>> Pattern implements a compiler for regular expressions as defined by the J2SE
>> specification. The regular expression syntax is largely similar to the
>> syntax defined by Perl 5 but has both omissions and extensions. A formal and
>> complete definition of the regular expression syntax is not provided by the
>> J2SE speTBD (TODO)
>>
>>
>> We Androids would love to contribute this documentation to Harmony.
>> Alongside improving the Harmony doc at large, it brings our copy of the code
>> closer in-sync with yours, which is a big win for us.
>>
>> Would Harmony like the Android Javadoc?
>>
>> How could we contribute it? I could start with a .patch for say, the regex
>> module, and we could work from there.
>>
>> Cheers,
>> Jesse
>>
> 

Mime
View raw message