More docstrings

beeref/bee_json.py

@@ -13,12 +13,19 @@
 # You should have received a copy of the GNU General Public License
 # along with BeeRef.  If not, see <https://www.gnu.org/licenses/>.
 
+"""BeeRef's native file handling.
+
+BeeRef files are JSON files with images embedded as base64-encoded PNG data.
+"""
+
 import json
 
 from beeref.items import BeePixmapItem
 
 
 class BeeJSONEncoder(json.JSONEncoder):
+    """If an object defines the method ``to_bee_json``, use it to
+    serialize the object to JSON."""
 
     def default(self, obj):
         if hasattr(obj, 'to_bee_json'):
@@ -31,6 +38,9 @@ def dumps(obj):
 
 
 class BeeJSONDecoder(json.JSONDecoder):
+    """If a dictionary in the JSON file defines the key ``cls``, we use
+    that class name and run the classmethod ``from_bee_json`` on it to
+    deserialize the object."""
 
     bee_classes = [BeePixmapItem]
 

beeref/gui.py

@@ -23,6 +23,7 @@ logger = logging.getLogger('BeeRef')
 
 
 class WelcomeOverlay(QtWidgets.QWidget):
+    """Some basic info to be displayed when the scene is empty."""
 
     txt = """<p>Paste or drop images here.</p>
              <p>Right-click for more options.</p>"""

beeref/items.py

@@ -13,6 +13,10 @@
 # You should have received a copy of the GNU General Public License
 # along with BeeRef.  If not, see <https://www.gnu.org/licenses/>.
 
+"""Classes for items that are added to the scene by the user (images,
+text).
+"""
+
 import base64
 import logging
 
@@ -25,6 +29,7 @@ logger = logging.getLogger('BeeRef')
 
 
 class BeePixmapItem(QtWidgets.QGraphicsPixmapItem):
+    """Class for images added by the user."""
 
     def __init__(self, image, filename=None):
         super().__init__(QtGui.QPixmap.fromImage(image))
@@ -57,6 +62,7 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem):
         return self.pixmap().size().height()
 
     def pixmap_to_str(self):
+        """Convert the pixmap data to a base64-encoded PNG for saving."""
         barray = QtCore.QByteArray()
         buffer = QtCore.QBuffer(barray)
         buffer.open(QtCore.QIODevice.OpenMode.WriteOnly)
@@ -67,11 +73,13 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem):
 
     @classmethod
     def qimage_from_str(self, data):
+        """Read the image date from a base64-encoded PNG for loading."""
         img = QtGui.QImage()
         img.loadFromData(base64.b64decode(data))
         return img
 
     def to_bee_json(self):
+        """For saving the item to BeeRefs native file format."""
         return {
             'cls': self.__class__.__name__,
             'scale': self.scale_factor,
@@ -83,6 +91,7 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem):
 
     @classmethod
     def from_bee_json(cls, obj):
+        """For loading an item from BeeRefs native file format."""
         img = cls.qimage_from_str(obj['pixmap'])
         item = cls(img, filename=obj.get('filename'))
         if 'scale' in obj:

beeref/scene.py

@@ -31,6 +31,12 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene):
             self.removeItem(item)
 
     def normalize_width_or_height(self, mode):
+        """Scale the selected images to have the same width or height, as
+        specified by ``mode``.
+
+        :param mode: "width" or "height".
+        """
+
         values = [getattr(i, mode) for i in self.selectedItems()]
         if not values:
             return
@@ -43,12 +49,18 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene):
             item.setScale(factor)
 
     def normalize_height(self):
+        """Scale selected images to the same height."""
         return self.normalize_width_or_height('height')
 
     def normalize_width(self):
+        """Scale selected images to the same width."""
         return self.normalize_width_or_height('width')
 
     def normalize_size(self):
+        """Scale selected images to the same size.
+
+        Size meaning the area = widh * height.
+        """
         sizes = [i.width * i.height for i in self.selectedItems()]
 
         if not sizes:
@@ -79,8 +91,12 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene):
         super().mousePressEvent(event)
 
     def items_for_export(self):
-        """Returns the items that are to be exported."""
+        """Returns the items that are to be exported.
 
-        # self.items() holds items in reverse order of addition
+        Items to be exported are items that implement ``to_bee_json``.
+        """
+
+        # self.items() holds items in reverse order of addition, so we
+        # need to reverse it for export
         return list(filter(lambda i: hasattr(i, 'to_bee_json'),
                            reversed(self.items())))

beeref/view.py

@@ -316,15 +316,15 @@ class BeeGraphicsView(QtWidgets.QGraphicsView):
             logger.info('Maximum scene size reached')
 
     def get_zoom_size(self, func):
-        """Calculates the size of the current items' bounding box
-        in the view's coordinates.
+        """Calculates the size of all items' bounding box in the view's
+        coordinates.
 
         This helps ensure that we never zoom out too much (scene
-        becomes so tiny that they become invisible) or zoom in too
+        becomes so tiny that items become invisible) or zoom in too
         much (causing overflow errors).
 
-        `func` is a function witch takes the width and height as
-        arguments and turns it into a number, for ex. `min` or `max`.
+        :param func: Function which takes the width and height as
+        arguments and turns it into a number, for ex. ``min`` or ``max``.
         """
 
         topleft = self.mapFromScene(