Add more docs and comments.

Rename store.store(_:) to store.cache(_:).

Riot/Modules/Room/Views/URLPreviews/URLPreviewView.swift

@@ -24,17 +24,20 @@ protocol URLPreviewViewDelegate: AnyObject {
 }
 
 @objcMembers
+/// A view to display `URLPreviewData` generated by the `URLPreviewManager`.
 class URLPreviewView: UIView, NibLoadable, Themable {
     // MARK: - Constants
     
     private static let sizingView = URLPreviewView.instantiate()
     
     private enum Constants {
+        /// The fixed width of the preview view.
         static let width: CGFloat = 267.0
     }
     
     // MARK: - Properties
     
+    /// The preview data to display in the view.
     var preview: URLPreviewData? {
         didSet {
             guard let preview = preview else {
@@ -62,6 +65,7 @@ class URLPreviewView: UIView, NibLoadable, Themable {
     // Use a strong reference to keep it around when deactivating.
     @IBOutlet var siteNameLabelHeightConstraint: NSLayoutConstraint!
     
+    /// Returns true when `titleLabel` has a non-empty string.
     private var hasTitle: Bool {
         guard let title = titleLabel.text else { return false }
         return !title.isEmpty
@@ -130,6 +134,7 @@ class URLPreviewView: UIView, NibLoadable, Themable {
     }
     
     // MARK: - Private
+    /// Tells the view to show in it's loading state.
     private func renderLoading() {
         // hide the content
         imageView.isHidden = true
@@ -140,6 +145,7 @@ class URLPreviewView: UIView, NibLoadable, Themable {
         loadingActivityIndicator.startAnimating()
     }
     
+    /// Tells the view to display it's loaded state for the supplied data.
     private func renderLoaded(_ preview: URLPreviewData) {
         // update preview content
         imageView.image = preview.image
@@ -147,10 +153,6 @@ class URLPreviewView: UIView, NibLoadable, Themable {
         titleLabel.text = preview.title
         descriptionLabel.text = preview.text
         
-        updateLayout()
-    }
-    
-    private func updateLayout() {
         // hide the loading interface
         loadingView.isHidden = true
         loadingActivityIndicator.stopAnimating()
@@ -158,16 +160,15 @@ class URLPreviewView: UIView, NibLoadable, Themable {
         // show the content
         textContainerView.isHidden = false
         
+        // tweak the layout depending on the content
         if imageView.image == nil {
             imageView.isHidden = true
             
-            // tweak the layout of labels
             siteNameLabelHeightConstraint.isActive = true
             descriptionLabel.numberOfLines = hasTitle ? 3 : 5
         } else {
             imageView.isHidden = false
             
-            // tweak the layout of labels
             siteNameLabelHeightConstraint.isActive = false
             descriptionLabel.numberOfLines = 2
         }