1 files changed, 53 insertions, 14 deletions
diff --git a/src/client/views/DocComponent.tsx b/src/client/views/DocComponent.tsx
index a25a8f77a..de4df1830 100644
--- a/src/client/views/DocComponent.tsx
+++ b/src/client/views/DocComponent.tsx
@@ -5,17 +5,17 @@ import { DateField } from '../../fields/DateField';
 import { Doc, DocListCast, Field, Opt } from '../../fields/Doc';
 import { AclAdmin, AclAugment, AclEdit, AclPrivate, AclReadonly, DocData } from '../../fields/DocSymbols';
 import { List } from '../../fields/List';
+import { RefField } from '../../fields/RefField';
 import { GetEffectiveAcl, inheritParentAcls } from '../../fields/util';
 import { DocumentType } from '../documents/DocumentTypes';
 import { DocUtils } from '../documents/Documents';
 import { DocumentManager } from '../util/DocumentManager';
+import { DragManager } from '../util/DragManager';
 import { ObservableReactComponent } from './ObservableReactComponent';
 import { CollectionFreeFormView } from './collections/collectionFreeForm';
-import { FieldViewProps, FocusViewOptions } from './nodes/FieldView';
 import { DocumentView, OpenWhere } from './nodes/DocumentView';
+import { FieldViewProps, FocusViewOptions } from './nodes/FieldView';
 import { PinProps } from './nodes/trails';
-import { RefField } from '../../fields/RefField';
-import { DragManager } from '../util/DragManager';
 
 /**
  * Shared interface among all viewBox'es (ie, react classes that render the contents of a Doc)
@@ -75,15 +75,25 @@ export function DocComponent<P extends DocComponentProps>() {
             makeObservable(this);
         }
 
-        //TODO This might be pretty inefficient if doc isn't observed, because computed doesn't cache then
+        /**
+         * This is the document being rendered.  In the case of a compound template, it
+         * may not be the actual document rendered and it also may not be the 'real' root document.
+         * Rather, it specifies the shared properties of all layouts of the document (eg, x,y,)
+         */
         get Document() {
             return this._props.Document;
         }
-        // This is the rendering data of a document -- it may be "The Document", or it may be some template document that holds the rendering info
+
+        /**
+         * This is the document being rendered.  It may be a template so it may or may no inherit from the data doc.
+         */
         @computed get layoutDoc() {
             return this._props.LayoutTemplateString ? this.Document : Doc.Layout(this.Document, this._props.LayoutTemplate?.());
         }
-        // This is the data part of a document -- ie, the data that is constant across all views of the document
+
+        /**
+         * This is the unique data repository for a dcoument that stores the intrinsic document data
+         */
         @computed get dataDoc() {
             return this.Document[DocData];
         }
@@ -109,19 +119,32 @@ export function ViewBoxBaseComponent<P extends FieldViewProps>() {
         get DocumentView() {
             return this._props.DocumentView;
         }
-        //TODO This might be pretty inefficient if doc isn't observed, because computed doesn't cache then
+
+        /**
+         * This is the document being rendered.  In the case of a compound template, it
+         * may not be the actual document rendered and it also may not be the 'real' root document.
+         * Rather, it specifies the shared properties of all layouts of the document (eg, x,y,)
+         */
         get Document() {
             return this._props.Document;
         }
-        // This is the rendering data of a document -- it may be "The Document", or it may be some template document that holds the rendering info
+        /**
+         * This is the document being rendered.  It may be a template so it may or may no inherit from the data doc.
+         */
         @computed get layoutDoc() {
             return Doc.Layout(this.Document);
         }
-        // This is the data part of a document -- ie, the data that is constant across all views of the document
+
+        /**
+         * This is the unique data repository for a dcoument that stores the intrinsic document data
+         */
         @computed get dataDoc() {
             return this.Document.isTemplateForField || this.Document.isTemplateDoc ? this._props.TemplateDataDocument ?? this.Document[DocData] : this.Document[DocData];
         }
-        // key where data is stored
+
+        /**
+         * this is the field key where the primary rendering data is stored for the layout doc (e.g., it's often the 'data' field for a collection, or the 'text' field for rich text)
+         */
         get fieldKey() {
             return this._props.fieldKey;
         }
@@ -154,23 +177,39 @@ export function ViewBoxAnnotatableComponent<P extends FieldViewProps>() {
         get DocumentView() {
             return this._props.DocumentView;
         }
-        //TODO This might be pretty inefficient if doc isn't observed, because computed doesn't cache then
+
+        /**
+         * This is the document being rendered.  In the case of a compound template, it
+         * may not be the actual document rendered and it also may not be the 'real' root document.
+         * Rather, it specifies the shared properties of all layouts of the document (eg, x,y,)
+         */
         @computed get Document() {
             return this._props.Document;
         }
-        // This is the rendering data of a document -- it may be "The Document", or it may be some template document that holds the rendering info
+        /**
+         * This is the document being rendered.  It may be a template so it may or may no inherit from the data doc.
+         */
         @computed get layoutDoc() {
             return Doc.Layout(this.Document);
         }
-        // This is the data part of a document -- ie, the data that is constant across all views of the document
+
+        /**
+         * This is the unique data repository for a dcoument that stores the intrinsic document data
+         */
         @computed get dataDoc() {
             return this.Document.isTemplateForField || this.Document.isTemplateDoc ? this._props.TemplateDataDocument ?? this.Document[DocData] : this.Document[DocData];
         }
 
-        // key where data is stored
+        /**
+         * this is the field key where the primary rendering data is stored for the layout doc (e.g., it's often the 'data' field for a collection, or the 'text' field for rich text)
+         */
         @computed get fieldKey() {
             return this._props.fieldKey;
         }
+
+        /**
+         * this is field key where the list of annotations is stored
+         */
         @computed public get annotationKey() {
             return this.fieldKey + (this._annotationKeySuffix() ? '_' + this._annotationKeySuffix() : '');
         }