Improves comments and readability for #270

tracim/tracim/controllers/page.py

         file_id = int(tg.request.controller_state.routing_args.get('file_id'))
         return 'all the pages of document {}'.format(file_id)
 
+    # FIXME https://github.com/tracim/tracim/issues/271
     @expose(content_type='image/jpeg')
     def get_one(self,
                 page_id: str='-1',
                                      revision_id=revision_id,
                                      args=args, kwargs=kwargs)
 
+    # FIXME https://github.com/tracim/tracim/issues/271
     @expose(content_type='application/pdf')
     def download_pdf_one(self,
                          page_id: str,

tracim/tracim/controllers/previews.py

 __all__ = ['PreviewsController']
 
 
+# FIXME https://github.com/tracim/tracim/issues/272
+# unused, future removal planned
 class PreviewsController(TIMRestController):
 
     pages = PagesController()

tracim/tracim/lib/content.py

 
         return revision
 
+    # INFO - A.P - 2017-07-03 - python file object getter
+    # in case of we cook a version of preview manager that allows a pythonic
+    # access to files
     # def get_one_revision_file(self, revision_id: int = None):
     #     """
     #     This function allows us to directly get a Python file object from its
         :return: The corresponding filepath
         """
         revision = self.get_one_revision(revision_id)
-
-        dpt = DepotManager.get()
-        # python 3.6 PEP 526 -- Syntax for Variable Annotations
-        # https://www.python.org/dev/peps/pep-0526/
-        # dpt_file_path: str = dpt.get(dpt_stored_file)._file_path
-        dpt_stored_file = dpt.get(revision.depot_file)
-        dpt_file_path = dpt.get(dpt_stored_file)._file_path
-
-        return dpt_file_path
+        depot = DepotManager.get()
+        depot_stored_file = depot.get(revision.depot_file)  # type: StoredFile
+        depot_file_path = depot_stored_file._file_path  # type: str
+        return depot_file_path
 
     def get_one_by_label_and_parent(
             self,

tracim/tracim/model/data.py

         server_default='',
     )
     file_mimetype = Column(Unicode(255),  unique=False, nullable=False, default='')
+    # TODO - A.P - 2017-07-03 - future removal planned
+    # file_content is to be replaced by depot_file, for now both coexist as
+    # this:
+    # - file_content data is still setted
+    # - newly created revision also gets depot_file data setted
+    # - access to the file of a revision from depot_file exclusively
+    # Here is the tasks workflow of the DB to OnDisk Switch :
+    # - Add depot_file "prototype style"
+    #   https://github.com/tracim/tracim/issues/233 - DONE
+    # - Integrate preview generator feature "prototype style"
+    #   https://github.com/tracim/tracim/issues/232 - DONE
+    # - Write migrations
+    #   https://github.com/tracim/tracim/issues/245
+    #   https://github.com/tracim/tracim/issues/246
+    # - Stabilize preview generator integration
+    #   includes dropping DB file content
+    #   https://github.com/tracim/tracim/issues/249
     file_content = deferred(Column(LargeBinary(), unique=False, nullable=True))
+    # INFO - A.P - 2017-07-03 - Depot Doc
+    # http://depot.readthedocs.io/en/latest/#attaching-files-to-models
+    # http://depot.readthedocs.io/en/latest/api.html#module-depot.fields
     depot_file = Column(UploadedFileField, unique=False, nullable=True)
     properties = Column('properties', Text(), unique=False, nullable=False, default='')
 

tracim/tracim/model/serializers.py

         )
 
         if content.type == ContentType.File:
-            dpt = DepotManager.get()
-            dpt_file = dpt.get(data_container.depot_file)
+            depot = DepotManager.get()
+            depot_stored_file = depot.get(data_container.depot_file)
             result.label = content.label
             result['file'] = DictLikeClass(
                 name=data_container.file_name,
-                size=dpt_file.content_length,
+                size=depot_stored_file.content_length,
                 mimetype=data_container.file_mimetype)
         return result