Set wallpaper from right click menu in Files app.

third_party/closure_compiler/externs/chrome_extensions.js

Index: third_party/closure_compiler/externs/chrome_extensions.js
diff --git a/third_party/closure_compiler/externs/chrome_extensions.js b/third_party/closure_compiler/externs/chrome_extensions.js
index ea1d2f249c8d6d976d10c14ddfef3dcfb59fcd61..bde2305c5030e24a817f0de6c47224829f8873f1 100644
--- a/third_party/closure_compiler/externs/chrome_extensions.js
+++ b/third_party/closure_compiler/externs/chrome_extensions.js
@@ -9159,3 +9159,35 @@ chrome.inlineInstallPrivate = {};
  *     (2) an error code in case of error
  */
 chrome.inlineInstallPrivate.install = function(id, opt_callback) {};
+
+/** @fileoverview Externs generated from namespace: wallpaper */
+
+/**
+ * @const

[ewa, 2016/02/23 22:15:47]

I was thinking there should be an @see link to the docs but, the @see's before
the types and methods is sufficient.

+ */
+chrome.wallpaper = {};
+
+/**
+ * @enum {string}
+ * @see https://developer.chrome.com/extensions/wallpaper#type-WallpaperLayout
+ */
+chrome.wallpaper.WallpaperLayout = {
+  STRETCH: 'STRETCH',
+  CENTER: 'CENTER',
+  CENTER_CROPPED: 'CENTER_CROPPED',
+};

[ewa, 2016/02/23 22:15:47]

The docs mention the chrome.wallpaper.WallpaperLayout as being an enum, but
lists the values as strings (specifically: "STRETCH", "CENTER", or
"CENTER_CROPPED").  The docs don't mention the enum value names used to
reference the strings.

Therefore, a developer does not know to use
chrome.wallpaper.WallpaperLayout.STRETCH and will, instead, use "STRETCH".

If the API is providing an enum with named fields for the values, then the docs
are not complete and that should be fixed.  Also, if the API is providing an
enum with named fields for the values, the enum should NOT be defined in an
externs file.  Defining enums in an externs file is no-no as developers will
never find them.

[Devlin, 2016/02/23 23:19:18]

Yes, the docs should be updated to indicate this.  However, that's not a reason
to not include them in the extern.  Developers *are* using these enums (and
chrome is too!) and if we remove them from the externs file, the code will fail
to compile (no object named Foo on chrome.bar).  Just because something isn't
well known doesn't mean the externs should be incorrect. ;)

[ewa, 2016/02/24 01:56:33]

Ok, I think we're making different points. 

For an enum provided by a library, the externs file needs to define the, well,
external things.  That includes the type name, chrome.wallpaper.WallpaperLayout
in this example, and it's members, STRETCH, CENTER and CENTER_CROPPED.  It
should not be defining the value of the names, 'STRETCH', 'CENTER' and
'CENTER_CROPPED', else we end up with Two Copies of the Truth (always bad).

An externs file is never the place to define something, rather, it's the place
to describe something that is defined elsewhere and to describe the names used
to reference those somethings so the compiler doesn't rename them.

Hmm, it's not entirely clear to me how the compiler handles enums in an externs
file.  For @enum, it probably requires there to be values as it likes valid JS. 
I ran some experiments and, yes, values are required.  The good news is that the
compiler did not replace the symbolic name with its value from the externs file
(that would have been a big mess).  I also tried setting their values to the
empty string and that worked.

If the param to is declared to be an enum, then the compiler complains if a
string is passed in.  Since the docs encourage the use of strings, the param
probably needs to be support both the enum or a string.

----

The lack of docs is reason to not include enums.  The enums may be used in
chrome, but's not relevant to this discussion as this is about extensions and
extension developers.  If extension developers are using them, then they made a
leap of faith that the enum member's name is identical to it's value.

That said, I have a suggestion below that allows the enum in the externs file
before docs have been fixed.


----
How to move forward? My suggestions:
1. The doc-generator needs to be fixed so the docs are fixed.
2. The enum can be included in the externs file, but the values should be empty
and uses must also accept strings.  By doing the latter, it's fine to include
the enum prior to getting the docs fixed.
3. Item 2 should be incorporated into the auto-generator as there are lots of
enums that are strings in the current chrome_extensions.js and dropping support
of strings will break code.

[Devlin, 2016/02/24 04:38:49]

I would say that anyone consuming *new* externs (which this is) should use enums
rather than strings - enums are more resilient.  We shouldn't make new externs
that permit old unsafe behavior.

Re "The enums may be used in chrome, but's not relevant to this discussion as
this is about extensions and extension developers." I don't really agree -
extensions are a chrome platform.  The source of truth is in chrome (and always
has been).  Chrome's behavior is very relevant, and is what externs should be
based upon.

Also, at the end of the day, please note that this is the chromium externs file,
which, for historical reasons, differs from the internal version (we're working
on more noticeably forking here).  This is precisely for some of these reasons -
that it doesn't make sense to have chrome pull in an external file based on
internal stuff.

+
+/**
+ * Sets wallpaper to the image at <em>url</em> or <em>wallpaperData</em> with
+ * the specified <em>layout</em>

[ewa, 2016/02/23 22:15:47]

No need for HTML markup in this comment.  In this file, it's distracting and not
helpful.

Since this is auto-generated, it would be best to change the auto-generator to
strip markup from descriptions.

[Devlin, 2016/02/23 23:19:18]

Agreed, it'd be good to not have the markup in the externs.  Patches welcome. :)

+ * @param {{
+ *   data: (!ArrayBuffer|undefined),
+ *   url: (string|undefined),
+ *   layout: !chrome.wallpaper.WallpaperLayout,
+ *   filename: string,
+ *   thumbnail: (boolean|undefined)
+ * }} details
+ * @param {function(?):void} callback

[ewa, 2016/02/23 22:15:47]

The callback's param should be an ArrayBuffer.

+ * @see https://developer.chrome.com/extensions/wallpaper#method-setWallpaper
+ */
+chrome.wallpaper.setWallpaper = function(details, callback) {};