diff --git a/lib/OpenLayers/Layer/OSM.js b/lib/OpenLayers/Layer/OSM.js
index 0531a9a7a8..320c4540ef 100644
--- a/lib/OpenLayers/Layer/OSM.js
+++ b/lib/OpenLayers/Layer/OSM.js
@@ -9,33 +9,82 @@
 
 /**
  * Class: OpenLayers.Layer.OSM
- * A class to access OpenStreetMap tiles. By default, uses the OpenStreetMap
- *    hosted tile.openstreetmap.org 'Mapnik' tileset. If you wish to use
- *    tiles@home / osmarender layer instead, you can pass a layer like:
+ * This layer allows accessing OpenStreetMap tiles. By default the OpenStreetMap
+ *    hosted tile.openstreetmap.org Mapnik tileset is used. If you wish to use
+ *    tiles@home / osmarender layer instead, you need to provide a different
+ *    URL to the constructor. Here's an example for tiles@home:
  * 
  * (code)
  *     new OpenLayers.Layer.OSM("t@h", 
  *       "http://tah.openstreetmap.org/Tiles/tile/${z}/${x}/${y}.png"); 
  * (end)
  *
- * This layer defaults to Spherical Mercator.
- * 
  * Inherits from:
  *  - <OpenLayers.Layer.XYZ>
  */
 OpenLayers.Layer.OSM = OpenLayers.Class(OpenLayers.Layer.XYZ, {
-     name: "OpenStreetMap",
-     attribution: "Data CC-By-SA by <a href='http://openstreetmap.org/'>OpenStreetMap</a>",
-     sphericalMercator: true,
-     url: 'http://tile.openstreetmap.org/${z}/${x}/${y}.png',
-     clone: function(obj) {
-         if (obj == null) {
-             obj = new OpenLayers.Layer.OSM(
-                 this.name, this.url, this.getOptions());
-         }
-         obj = OpenLayers.Layer.XYZ.prototype.clone.apply(this, [obj]);
-         return obj;
-     },
-     wrapDateLine: true,
-     CLASS_NAME: "OpenLayers.Layer.OSM"
+
+    /**
+     * APIProperty: name
+     * {String} The layer name. Defaults to "OpenStreetMap" if the first
+     * argument to the constructor is null or undefined.
+     */
+    name: "OpenStreetMap",
+
+    /**
+     * APIProperty: url
+     * {String} The tileset URL scheme. Defaults to
+     * : http://tile.openstreetmap.org/${z}/${x}/${y}.png
+     * (the official OSM tileset) if the second argument to the constructor
+     * is null or undefined. To use another tileset you can have something
+     * like this:
+     * (start code)
+     *     new OpenLayers.Layer.OSM("t@h", 
+     *       "http://tah.openstreetmap.org/Tiles/tile/${z}/${x}/${y}.png"); 
+     * (end)
+     */
+    url: 'http://tile.openstreetmap.org/${z}/${x}/${y}.png',
+
+    /**
+     * Property: attribution
+     * {String} The layer attribution.
+     */
+    attribution: "Data CC-By-SA by <a href='http://openstreetmap.org/'>OpenStreetMap</a>",
+
+    /**
+     * Property: sphericalMercator
+     * {Boolean}
+     */
+    sphericalMercator: true,
+
+    /**
+     * Property: wrapDateLine
+     * {Boolean}
+     */
+    wrapDateLine: true,
+
+    /**
+     * Constructor: OpenLayers.Layer.OSM
+     *
+     * Parameters:
+     * name - {String} The layer name.
+     * url - {String} The tileset URL scheme.
+     * options - {Object} Configuration options for the layer. Any inherited
+     *     layer option can be set in this object (e.g.
+     *     <OpenLayers.Layer.Grid.buffer>).
+     */
+
+    /**
+     * Method: clone
+     */
+    clone: function(obj) {
+        if (obj == null) {
+            obj = new OpenLayers.Layer.OSM(
+                this.name, this.url, this.getOptions());
+        }
+        obj = OpenLayers.Layer.XYZ.prototype.clone.apply(this, [obj]);
+        return obj;
+    },
+
+    CLASS_NAME: "OpenLayers.Layer.OSM"
 });