Add comments

2 files changed, 18 insertions, 0 deletions

diff --git a/document/src/vespa/document/datatype/referencedatatype.h b/document/src/vespa/document/datatype/referencedatatype.h
index 9fbd9c70002..5a39addead1 100644
--- a/document/src/vespa/document/datatype/referencedatatype.h
+++ b/document/src/vespa/document/datatype/referencedatatype.h
@@ -6,6 +6,10 @@
 
 namespace document {
 
+/**
+ * A ReferenceDataType specifies a particular concrete document type that a
+ * ReferenceFieldValue instance binds to.
+ */
 class ReferenceDataType : public DataType {
     const DocumentType& _targetDocType;
 public:
diff --git a/document/src/vespa/document/fieldvalue/referencefieldvalue.h b/document/src/vespa/document/fieldvalue/referencefieldvalue.h
index be8801cd4d2..12f61f0eb11 100644
--- a/document/src/vespa/document/fieldvalue/referencefieldvalue.h
+++ b/document/src/vespa/document/fieldvalue/referencefieldvalue.h
@@ -8,6 +8,20 @@
 
 namespace document {
 
+/**
+ * A reference field value allows search queries to access fields in other
+ * document instances as if they were fields natively stored within the
+ * searched document. This allows modelling one-to-many relations such as a
+ * parent document with many children containing references back to the parent.
+ *
+ * Each ReferenceFieldValue may contain a single document ID which specifies the
+ * instance the field should refer to. This document ID must have a type
+ * matching that of the reference data type of the field itself.
+ *
+ * Note that references are not polymorphic. This means that if you have a
+ * document type "foo" inheriting "bar", you cannot have a reference<bar> field
+ * containing a document ID for a "foo" document.
+ */
 class ReferenceFieldValue : public FieldValue {
     const ReferenceDataType* _dataType;
     // TODO wrap in std::optional once available.