Added library-level comments for polymer and polymer_expressions

Added library-level comments for polymer and polymer_expressions


BUG=
R=kathyw@google.com

Committed: https://code.google.com/p/dart/source/detail?r=27504

[mem, 2013-09-04 20:21:29]

Added library-level comments for polymer and polymer_expressions.

NOTE: the links to the "polymer.dart home page" and to the "Upgrading to
Polymer.dart" don't work yet. They will link to pages that Seth is working on. 

I appreciate your feedback.

thanks.
mem

[sethladd, 2013-09-04 20:40:22]

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:11: * Polymer expressions
are part of the Polymer.dart project.
I think it's one word: PolymerExpressions

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:17: * To use the
polymer_expressions package in your application,
Is it useful to use polymer_expressions without polymer? maybe just say that you
get polymer_expressions when you install polymer.

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:29: * * Check out the
source code for the polymer expressions package
you're not really checking out the source code at pub. How about "Learn more
about polymer_expressions package at pub ..."

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:33: * * If you were using
Web UI in your apps,
It's OK if you drop this, since we mention this on the polymer library doc.

[Jennifer Messerly, 2013-09-04 22:09:35]

LGTM w/ Seth's suggested fixes. Thank you so much for adding these!

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer/lib/polyme...
File pkg/polymer/lib/polymer.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer/lib/polyme...
pkg/polymer/lib/polymer.dart:18: *       polymer: any
should we add a suggestion to get the current major release number from
pub.dartlang.org/packages/polymer and use that here instead of "any"?

for example, if starting a new Polymer app now I would want to use

">=0.7.1 <0.8"

as described here: http://pub.dartlang.org/doc/dependencies.html


(we could make this change later too, of course)

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:11: * Polymer expressions
are part of the Polymer.dart project.
On 2013/09/04 20:40:22, sethladd wrote:
> I think it's one word: PolymerExpressions

so far we have been using two words in the readme:
http://pub.dartlang.org/packages/polymer_expressions

but I dunno if that's right.

@mem if you want to take a shot at fixing the README.md files too that would be
very welcome :)

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:17: * To use the
polymer_expressions package in your application,
On 2013/09/04 20:40:22, sethladd wrote:
> Is it useful to use polymer_expressions without polymer? maybe just say that
you
> get polymer_expressions when you install polymer.

It could be, if you are using data binding only.
But I agree -- it is better to give folks the "batteries included" complete
framework.

[sethladd, 2013-09-04 22:21:14]

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:11: * Polymer expressions
are part of the Polymer.dart project.
Looks like they updated their site.
http://www.polymer-project.org/docs/polymer/expressions.html  It's just
"expressions" now. So two words is fine. Good to know!

[mem, 2013-09-09 18:40:17]

Modified the README files for polymer and polymer_expressions.
Also changed the homepage in the pubspec.yaml files to the new
dartlang.org/polymer-dart page.

I can't generate the files and use the new doc-viewer to look at them, so I
can't test the links right now.

Thanks in advance for your insightful feedback.
mem

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer/lib/polyme...
File pkg/polymer/lib/polymer.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer/lib/polyme...
pkg/polymer/lib/polymer.dart:18: *       polymer: any
On 2013/09/04 22:09:35, John Messerly wrote:
> should we add a suggestion to get the current major release number from
> pub.dartlang.org/packages/polymer and use that here instead of "any"?
> 
> for example, if starting a new Polymer app now I would want to use
> 
> ">=0.7.1 <0.8"
> 
> as described here: http://pub.dartlang.org/doc/dependencies.html
> 
> 
> (we could make this change later too, of course)

Done.

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:11: * Polymer expressions
are part of the Polymer.dart project.
I'll take a look at the README on Monday.

mem
On 2013/09/04 22:09:35, John Messerly wrote:
> On 2013/09/04 20:40:22, sethladd wrote:
> > I think it's one word: PolymerExpressions
> 
> so far we have been using two words in the readme:
> http://pub.dartlang.org/packages/polymer_expressions
> 
> but I dunno if that's right.
> 
> @mem if you want to take a shot at fixing the README.md files too that would
be
> very welcome :)

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:17: * To use the
polymer_expressions package in your application,
On 2013/09/04 20:40:22, sethladd wrote:
> Is it useful to use polymer_expressions without polymer? maybe just say that
you
> get polymer_expressions when you install polymer.

Done.

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:29: * * Check out the
source code for the polymer expressions package
On 2013/09/04 20:40:22, sethladd wrote:
> you're not really checking out the source code at pub. How about "Learn more
> about polymer_expressions package at pub ..."

Done.

https://chromiumcodereview.appspot.com/23453034/diff/1/pkg/polymer_expression...
pkg/polymer_expressions/lib/polymer_expressions.dart:33: * * If you were using
Web UI in your apps,
On 2013/09/04 20:40:22, sethladd wrote:
> It's OK if you drop this, since we mention this on the polymer library doc.

Done.

[kevmoo-old, 2013-09-09 20:54:24]

FYI

https://codereview.chromium.org/23453034/diff/9001/pkg/polymer/pubspec.yaml
File pkg/polymer/pubspec.yaml (right):

https://codereview.chromium.org/23453034/diff/9001/pkg/polymer/pubspec.yaml#n...
pkg/polymer/pubspec.yaml:7: homepage: https://www.dartlang.org/polymer-dart/
Got ahead of you here: https://code.google.com/p/dart/source/detail?r=27310

[justinfagnani, 2013-09-10 00:49:20]

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
File pkg/polymer_expressions/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:5: Polymer expressions are an expressive
syntax that can be used in templates in
I think we should say what kind of templates. "HTML templates", "MDV templates"?
I'm not sure what the official terminology is at this moment.

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:8: Templates are one feature of
Polymer.dart—a set of comprehensive UI
spaces around the dash? not sure how that should be

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:12: because polymer expressions are often used
in polymer Dart apps.
often used -> the default expression syntax

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:12: because polymer expressions are often used
in polymer Dart apps.
should "polymer" be capitalized?

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/lib/polymer_expressions.dart:6: * A syntax used with
polymer elements that
capitalize "polymer"?

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/lib/polymer_expressions.dart:6: * A syntax used with
polymer elements that
syntax -> binding delegate?

[Jennifer Messerly, 2013-09-10 02:29:07]

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
File pkg/polymer_expressions/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:5: Polymer expressions are an expressive
syntax that can be used in templates in
On 2013/09/10 00:49:20, justinfagnani wrote:
> I think we should say what kind of templates. "HTML templates", "MDV
templates"?
> I'm not sure what the official terminology is at this moment.

just wanted to remind: we shouldn't use "mdv" anywhere... the term is dead. Long
live MDV :)
https://github.com/Polymer/TemplateBinding

here is the official word:
http://www.polymer-project.org/docs/polymer/databinding.html

Personally, I think "templates" is plenty specific. It *is* the HTML <template>
element, after all :)

https://chromiumcodereview.appspot.com/23453034/diff/1003/pkg/polymer_express...
pkg/polymer_expressions/README.md:8: Templates are one feature of
Polymer.dart&mdash;a set of comprehensive UI
On 2013/09/10 00:49:20, justinfagnani wrote:
> spaces around the dash? not sure how that should be

fwiw, &mdash; is not very Markdow-ish, since the intent of Markdown is to be
readable without a tool.

Perhaps the unicode mdash char (U+2014), or just "--" ?

[mem, 2013-09-11 20:53:30]

Thanks for the feedback. Let me know if there's anything else.

mem

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/RE...
File pkg/polymer_expressions/README.md (right):

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/RE...
pkg/polymer_expressions/README.md:5: Polymer expressions are an expressive
syntax that can be used in templates in
On 2013/09/10 00:49:20, justinfagnani wrote:
> I think we should say what kind of templates. "HTML templates", "MDV
templates"?
> I'm not sure what the official terminology is at this moment.

Done.

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/RE...
pkg/polymer_expressions/README.md:8: Templates are one feature of
Polymer.dart—a set of comprehensive UI
On 2013/09/10 02:29:07, John Messerly wrote:
> On 2013/09/10 00:49:20, justinfagnani wrote:
> > spaces around the dash? not sure how that should be
> 
> fwiw, — is not very Markdow-ish, since the intent of Markdown is to be
> readable without a tool.
> 
> Perhaps the unicode mdash char (U+2014), or just "--" ?

Done.

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/RE...
pkg/polymer_expressions/README.md:12: because polymer expressions are often used
in polymer Dart apps.
On 2013/09/10 00:49:20, justinfagnani wrote:
> often used -> the default expression syntax

Done.

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/li...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/li...
pkg/polymer_expressions/lib/polymer_expressions.dart:6: * A syntax used with
polymer elements that
On 2013/09/10 00:49:20, justinfagnani wrote:
> capitalize "polymer"?

Done.

https://codereview.chromium.org/23453034/diff/1003/pkg/polymer_expressions/li...
pkg/polymer_expressions/lib/polymer_expressions.dart:6: * A syntax used with
polymer elements that
On 2013/09/10 00:49:20, justinfagnani wrote:
> syntax -> binding delegate?

Done.

[mem, 2013-09-13 16:19:40]

I think I've done everything they've asked but I haven't gotten a LGTM yet.

Could you give it a look? Do I bug them again?

Thanks.
mem

[Kathy Walrath, 2013-09-13 16:44:15]

I can't speak for the others, but lgtm.

I do, of course, have some minor suggestions.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README.md
File pkg/polymer/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README...
pkg/polymer/README.md:23: installation instructions, how to upgrade from Web UI,
"how to upgrade from Web UI" isn't parallel with the other items in the list.
Maybe:

help for converting from Web UI

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README...
pkg/polymer/README.md:33: [polymer_expressions][polymer_expressions] package,
I think the second [] can be empty

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
File pkg/polymer/lib/polymer.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:20: *       polymer: '>=0.7.1 <0.8'
Clarify whether these particular version numbers are just an example or our
recommendation of what they should use.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:22: * (For details about package dependencies and
version constraints,
Move this up above the example. Maybe just make "dependency" a link? ("...first
add a [dependency]...")

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:31: * * Refer to the
I'd prefer to put the links first, so they're in a consistent place. Maybe:

* [Polymer.dart homepage](...): Example code, ....
* [Polymer.dart package homepage](...): More details, such as the current major
release number.
* [Upgrading to Polymer.dart](...): Tips for converting your apps from Web UI to
Polymer.dart.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
File pkg/polymer_expressions/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:8: Templates are one feature of Polymer.dart
-- a set of comprehensive UI
Can you use the character '—' (shift-option-dash on a Mac)?

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:14: The [Polymer.dart home page][home_page]
I believe Google style is to say "homepage".

In fact, when I use Google to search for "homepage" or "home page", I get an ad:
"Make Google Your Homepage"!

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:16: installation instructions, tips for
upgrading from Web UI,
hey, you worded the Web UI thing better here

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/lib/polymer_expressions.dart:17: * home page for example
code, project status, and
homepage!

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/lib/polymer_expressions.dart:20: * ## Other resources
I've been using "See also". This is fine for now, but we should figure out the
right thing to do.

[mem, 2013-09-13 17:05:57]

ptal.

mem

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README.md
File pkg/polymer/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README...
pkg/polymer/README.md:23: installation instructions, how to upgrade from Web UI,
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> "how to upgrade from Web UI" isn't parallel with the other items in the list.
> Maybe:
> 
> help for converting from Web UI

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/README...
pkg/polymer/README.md:33: [polymer_expressions][polymer_expressions] package,
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> I think the second [] can be empty

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
File pkg/polymer/lib/polymer.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:20: *       polymer: '>=0.7.1 <0.8'
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> Clarify whether these particular version numbers are just an example or our
> recommendation of what they should use.

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:22: * (For details about package dependencies and
version constraints,
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> Move this up above the example. Maybe just make "dependency" a link?
("...first
> add a [dependency]...")

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer/lib/po...
pkg/polymer/lib/polymer.dart:31: * * Refer to the
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> I'd prefer to put the links first, so they're in a consistent place. Maybe:
> 
> * [Polymer.dart homepage](...): Example code, ....
> * [Polymer.dart package homepage](...): More details, such as the current
major
> release number.
> * [Upgrading to Polymer.dart](...): Tips for converting your apps from Web UI
to
> Polymer.dart.

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
File pkg/polymer_expressions/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:8: Templates are one feature of Polymer.dart
-- a set of comprehensive UI
It just looks like a regular dash. I even tried to copy the one you used.
Is comma better?

mem

On 2013/09/13 16:44:16, Kathy Walrath wrote:
> Can you use the character '—' (shift-option-dash on a Mac)?

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:14: The [Polymer.dart home page][home_page]
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> I believe Google style is to say "homepage".
> 
> In fact, when I use Google to search for "homepage" or "home page", I get an
ad:
> "Make Google Your Homepage"!

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:16: installation instructions, tips for
upgrading from Web UI,
:-)

Just testing your editing skills!
mem

On 2013/09/13 16:44:16, Kathy Walrath wrote:
> hey, you worded the Web UI thing better here

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
File pkg/polymer_expressions/lib/polymer_expressions.dart (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/lib/polymer_expressions.dart:17: * home page for example
code, project status, and
On 2013/09/13 16:44:16, Kathy Walrath wrote:
> homepage!

Done.

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/lib/polymer_expressions.dart:20: * ## Other resources
Shoot. I've been using Other resources everywhere.
mem

On 2013/09/13 16:44:16, Kathy Walrath wrote:
> I've been using "See also". This is fine for now, but we should figure out the
> right thing to do.

[Kathy Walrath, 2013-09-13 19:59:55]

lgtm (one note about —)

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
File pkg/polymer_expressions/README.md (right):

https://chromiumcodereview.appspot.com/23453034/diff/19001/pkg/polymer_expres...
pkg/polymer_expressions/README.md:8: Templates are one feature of Polymer.dart
-- a set of comprehensive UI
I think it looks like a regular dash in vim or reviews because they use a
fixed-width font. It seems to look right in the generated docs.

On 2013/09/13 17:05:58, mem wrote:
> It just looks like a regular dash. I even tried to copy the one you used.
> Is comma better?
> 
> mem
> 
> On 2013/09/13 16:44:16, Kathy Walrath wrote:
> > Can you use the character '—' (shift-option-dash on a Mac)?
>

[mem, 2013-09-13 21:28:58]

Committed patchset #8 manually as r27504 (presubmit successful).