Mailing-List: contact dev-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Received-SPF: pass (athena.apache.org: domain of jessewilson@google.com
 designates 216.239.33.17 as permitted sender)
DomainKey-Signature: a=rsa-sha1; s=beta; d=google.com; c=nofws; q=dns;
	h=mime-version:from:date:message-id:subject:to:content-type:x-system-of-record;
	b=KNGl9KUTWn9maHkw6LUSELpwWTXHmMShF/uTPSQQtyWxkrUyuP2QQNmTJjotir1c7
	LLA2h5DczT8aqZMwGt6LA==
MIME-Version: 1.0
From: Jesse Wilson <jessewilson@google.com>
Date: Thu, 16 Apr 2009 18:05:17 -0700
Message-ID: <a43fbc6a0904161805wfbe648fobb63d9ee991900d2@mail.gmail.com>
Subject: Android Javadocs
To: dev@harmony.apache.org
Content-Type: multipart/alternative; boundary=001636e0a79804fea90467b5c70c

--001636e0a79804fea90467b5c70c
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

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

--001636e0a79804fea90467b5c70c--