Merge pull request #344 from BibMartin/doctring_end

Complete docstrings

Author: ocefpaf

folium/colormap.py

@@ -264,8 +264,13 @@ class ColorMap(MacroElement):
 
     Parameters
     ----------
-    TODO: docstring"""
-
+    vmin: float
+        The left bound of the color scale.
+    vmax: float
+        The right bound of the color scale.
+    caption: str
+        A caption to draw with the colormap.
+    """
     def __init__(self, vmin=0., vmax=1., caption=""):
         super(ColorMap, self).__init__()
         self._name = 'ColorMap'
@@ -278,7 +283,7 @@ def __init__(self, vmin=0., vmax=1., caption=""):
         self._template = self._env.get_template('color_scale.js')
 
     def render(self, **kwargs):
-        """TODO: docstring"""
+        """Renders the HTML representation of the element."""
         self.color_domain = [self.vmin + (self.vmax-self.vmin) * k/499. for
                              k in range(500)]
         self.color_range = [self.__call__(x) for x in self.color_domain]

folium/element.py

@@ -25,7 +25,15 @@ class Element(object):
 
     Parameters
     ----------
-    TODO: docstring.
+    template: str, default None
+        A jinaj2-compatible template string for rendering the element.
+        If None, template will be:
+            {% for name, element in this._children.items() %}
+                {{element.render(**kwargs)}}
+            {% endfor %}
+        so that all the element's children are rendered.
+    template_name: str, default None
+        If no template is provided, you can also provide a filename.
     """
     def __init__(self, template=None, template_name=None):
         self._name = 'Element'
@@ -42,7 +50,10 @@ def __init__(self, template=None, template_name=None):
         """)
 
     def get_name(self):
-        """TODO: docstring."""
+        """Returns a string representation of the object.
+        This string has to be unique and to be a python and javascript-compatible
+        variable name.
+        """
         return _camelify(self._name) + '_' + self._id
 
     def _get_self_bounds(self):
@@ -95,7 +106,7 @@ def add_to(self, parent, name=None, index=None):
         return self
 
     def to_dict(self, depth=-1, ordered=True, **kwargs):
-        """TODO: docstring."""
+        """Returns a dict representation of the object."""
         if ordered:
             dict_fun = OrderedDict
         else:
@@ -109,7 +120,7 @@ def to_dict(self, depth=-1, ordered=True, **kwargs):
         return out
 
     def to_json(self, depth=-1, **kwargs):
-        """TODO: docstring."""
+        """Returns a JSON representation of the object."""
         return json.dumps(self.to_dict(depth=depth, ordered=True), **kwargs)
 
     def get_root(self):
@@ -146,15 +157,15 @@ def save(self, outfile, close_file=True, **kwargs):
 
 
 class Link(Element):
-    """TODO: docstring."""
+    """An abstract class for embedding a link in the HTML."""
     def get_code(self):
-        """TODO : docstring."""
+        """Opens the link and returns the response's content."""
         if self.code is None:
             self.code = urlopen(self.url).read()
         return self.code
 
     def to_dict(self, depth=-1, **kwargs):
-        """TODO : docstring."""
+        """Returns a dict representation of the object."""
         out = super(Link, self).to_dict(depth=-1, **kwargs)
         out['url'] = self.url
         return out
@@ -331,15 +342,15 @@ def __init__(self, width="100%", height=None, ratio="60%", figsize=None):
             """), name='css_style')
 
     def to_dict(self, depth=-1, **kwargs):
-        """TODO: docstring."""
+        """Returns a dict representation of the object."""
         out = super(Figure, self).to_dict(depth=depth, **kwargs)
         out['header'] = self.header.to_dict(depth=depth-1, **kwargs)
         out['html'] = self.html.to_dict(depth=depth-1, **kwargs)
         out['script'] = self.script.to_dict(depth=depth-1, **kwargs)
         return out
 
     def get_root(self):
-        """TODO: docstring."""
+        """Returns the root of the elements tree."""
         return self
 
     def render(self, **kwargs):
@@ -375,7 +386,21 @@ def _repr_html_(self, **kwargs):
         return iframe
 
     def add_subplot(self, x, y, n, margin=0.05):
-        """TODO: docstring."""
+        """Creates a div child subplot in a matplotlib.figure.add_subplot style.
+
+        Parameters
+        ----------
+        x : int
+            The number of rows in the grid.
+        y : int
+            The number of columns in the grid.
+        n : int
+            The cell number in the grid, counted from 1 to x*y.
+
+        Example:
+        >>> fig.add_subplot(3,2,5)
+        # Create a div in the 5th cell of a 3rows x 2columns grid(bottom-left corner).
+        """
         width = 1./y
         height = 1./x
         left = ((n-1) % y)*width
@@ -427,11 +452,21 @@ def __init__(self, data, width="100%", height="100%"):
 
 
 class Div(Figure):
-    """Create a Map with Folium and Leaflet.js.
+    """Create a Div to be embedded in a Figure.
 
     Parameters
     ----------
-    TODO: docstring.
+    width: int or str, default '100%'
+        The width of the div in pixels (int) or percentage (str).
+    height: int or str, default '100%'
+        The height of the div in pixels (int) or percentage (str).
+    left: int or str, default '0%'
+        The left-position of the div in pixels (int) or percentage (str).
+    top: int or str, default '0%'
+        The top-position of the div in pixels (int) or percentage (str).
+    position: str, default 'relative'
+        The position policy of the div.
+        Usual values are 'relative', 'absolute', 'fixed', 'static'.
     """
     def __init__(self, width='100%', height='100%',
                  left="0%", top="0%", position='relative'):
@@ -475,7 +510,7 @@ def __init__(self, width='100%', height='100%',
         """)
 
     def get_root(self):
-        """TODO: docstring."""
+        """Returns the root of the elements tree."""
         return self
 
     def render(self, **kwargs):

folium/features.py

@@ -138,7 +138,7 @@ def __init__(self, location, color='black', opacity=1, weight=2,
             """)
 
     def render(self, **kwargs):
-        """TODO: docstring."""
+        """Renders the HTML representation of the element."""
         super(RegularPolygonMarker, self).render()
 
         figure = self.get_root()
@@ -197,7 +197,7 @@ def __init__(self, data, width=None, height=None,
         self._template = Template(u"")
 
     def render(self, **kwargs):
-        """TODO: docstring"""
+        """Renders the HTML representation of the element."""
         self.json = json.dumps(self.data)
 
         self._parent.html.add_children(Element(Template("""
@@ -322,7 +322,9 @@ def style_function(x): return {}
             """)  # noqa
 
     def style_data(self):
-        """TODO: docstring."""
+        """Applies self.style_function to each feature of self.data and returns a corresponding
+        JSON output.
+        """
         if 'features' not in self.data.keys():
             # Catch case when GeoJSON is just a single Feature or a geometry.
             if not (isinstance(self.data, dict) and 'geometry' in self.data.keys()):  # noqa
@@ -438,7 +440,9 @@ def style_function(x): return {}
             """)  # noqa
 
     def style_data(self):
-        """TODO: docstring."""
+        """Applies self.style_function to each feature of self.data and returns a corresponding
+        JSON output.
+        """
         def recursive_get(data, keys):
             if len(keys):
                 return recursive_get(data.get(keys[0]), keys[1:])
@@ -450,7 +454,7 @@ def recursive_get(data, keys):
         return json.dumps(self.data, sort_keys=True)
 
     def render(self, **kwargs):
-        """TODO: docstring."""
+        """Renders the HTML representation of the element."""
         super(TopoJson, self).render(**kwargs)
 
         figure = self.get_root()
@@ -516,7 +520,7 @@ def __init__(self, name=None, overlay=True, control=True):
             """)
 
     def render(self, **kwargs):
-        """TODO: docstring"""
+        """Renders the HTML representation of the element."""
         super(MarkerCluster, self).render()
 
         figure = self.get_root()

folium/map.py

@@ -179,7 +179,9 @@ def add_tile_layer(self, tiles='OpenStreetMap', name=None,
                        API_key=None, max_zoom=18, min_zoom=1,
                        attr=None, tile_name=None, tile_url=None,
                        active=False, detect_retina=False, **kwargs):
-        """TODO: docstring."""
+        """Add a tile layer to the map.
+
+        See TileLayer for options."""
         if tile_name is not None:
             name = tile_name
             warnings.warn("'tile_name' is deprecated. Use 'name' instead.")
@@ -487,7 +489,15 @@ def _get_self_bounds(self):
 
 
 class Popup(Element):
-    """TODO: docstring."""
+    """Create a Popup instance that can be linked to a Layer.
+
+    Parameters
+    ----------
+    html: string or Element
+        Content of the Popup.
+    max_width: int, default 300
+        The maximal width of the popup.
+    """
     def __init__(self, html=None, max_width=300):
         super(Popup, self).__init__()
         self._name = 'Popup'