From 1a0d8a4aa97214df97e5965b2a64b3a5ae144388 Mon Sep 17 00:00:00 2001
From: Cheng Zhao <zcbenz@gmail.com>
Date: Mon, 23 Jun 2014 22:58:42 +0800
Subject: [PATCH] :memo: Add docs on image support in atom-shell.

---
 docs/api/browser-window.md |  2 +-
 docs/api/image.md          | 25 +++++++++++++++++++++++++
 docs/api/tray.md           |  6 +++---
 3 files changed, 29 insertions(+), 4 deletions(-)
 create mode 100644 docs/api/image.md

diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index d6391ce6ca82..84f3fdf5f4c1 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -47,7 +47,7 @@ You can also create a window without chrome by using
     zoom percent / 100, so `3.0` represents `300%`
   * `kiosk` Boolean - The kiosk mode
   * `title` String - Default window title
-  * `icon` String - The path of icon file
+  * `icon` [Image](image.md) - The window icon
   * `show` Boolean - Whether window should be shown when created
   * `frame` Boolean - Specify `false` to create a
     [Frameless Window](frameless-window.md)
diff --git a/docs/api/image.md b/docs/api/image.md
new file mode 100644
index 000000000000..a18e3e8ae1a5
--- /dev/null
+++ b/docs/api/image.md
@@ -0,0 +1,25 @@
+# Image
+
+In atom-shell images are represented by their file paths, we currently do not
+support in-memory images or remote images.
+
+For example when creating tray or setting window's icon, you can pass image's
+file path as `String` to represent an image:
+
+```javascript
+var appIcon = new Tray('/Users/somebody/images/icon@2x.png');
+var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'});
+```
+
+## Supported formats
+
+Only `PNG` and `JPG` formats are supported, and `PNG` format is preferred.
+
+## High resolution image
+
+On platforms that have high-DPI support, you can append `@2x` after image's
+file name's base name to mark it as a high resolution image.
+
+For example if `icon.png` is a normal image that has standard resolution, the
+`icon@2x.png` would be treated as a high resolution image that has double DPI
+dense.
diff --git a/docs/api/tray.md b/docs/api/tray.md
index 01aca310522c..ebdeae3d0dcc 100644
--- a/docs/api/tray.md
+++ b/docs/api/tray.md
@@ -40,7 +40,7 @@ rely on `clicked` event and always attach a context menu to the tray icon.
 
 ### new Tray(image)
 
-* `image` String
+* `image` [Image](image.md)
 
 Creates a new tray icon associated with the `image`.
 
@@ -50,13 +50,13 @@ Emitted when the tray icon is clicked.
 
 ### Tray.setImage(image)
 
-* `image` String
+* `image` [Image](image.md)
 
 Sets the `image` associated with this tray icon.
 
 ### Tray.setPressedImage(image)
 
-* `image` String
+* `image` [Image](image.md)
 
 Sets the `image` associated with this tray icon when pressed.