Improved documentation

datastore/protobuf/datastore.proto

@@ -76,7 +76,7 @@ message TSMetadata {
   repeated Link links = 1;
   // --- END non-string metadata -----------------
 
-  // --- BEGIN string metadata -----------------
+  // --- BEGIN string metadata (handleable with reflection) -----------------
   string version = 2;
   string type = 3;
   string title = 4;
@@ -115,7 +115,7 @@ message ObsMetadata {
   google.protobuf.Timestamp pubtime = 5;
   // --- END non-string metadata -----------------
 
-  // --- BEGIN string metadata -----------------
+  // --- BEGIN string metadata (handleable with reflection) -----------------
   string id = 6;
   string data_id = 7 [json_name = "data_id"];
   string history = 8;
@@ -152,14 +152,29 @@ message PutObsResponse {
 //---------------------------------------------------------------------------
 
 message GetObsRequest {
-  // --- BEGIN special handling of temporal and spatial search -----------------
+  // --- BEGIN non-string metadata -------------------------
+
+  // temporal search
   TimeInterval interval = 1; // only return observations in this time range
+
+  // spatial search
   Polygon inside = 2; // if specified, only return observations in this area
-  // --- END special handling of temporal and spatial search -----------------
 
-  // --- BEGIN general handling of strings; field names must correspond exactly with string field names in TSMetadata or ObsMetadata -----
-  // - if the field F is specified (where F is for example 'platform'), only observations matching at least one these values for F will be returned
-  // - if the field F is not specified, filtering on F is effectively disabled
+  // search wrt. TSMetadata.links
+  // TODO - needs special handling
+
+  // --- END non-string metadata -------------------------
+
+
+  // --- BEGIN string metadata (handleable with reflection) -------------------------
+  //
+  //   - field names must correspond exactly with string field names in TSMetadata or ObsMetadata
+  //
+  //   - if the field F is specified (where F is for example 'platform'), only observations
+  //     matching at least one these values for F will be returned
+  //
+  //   - if the field F is not specified, filtering on F is effectively disabled
+
   repeated string version = 3;
   repeated string type = 4;
   repeated string title = 5;
@@ -187,11 +202,7 @@ message GetObsRequest {
   repeated string history = 27;
   repeated string metadata_id = 28 [json_name = "metadata_id"];
   repeated string processing_level = 29 [json_name = "processing_level"];
-  // --- END general handling of strings -----
-
-  // --- BEGIN special handling of 'repeated Link' ------
-  // TODO
-  // --- END special handling of 'repeated Link' ------
+  // --- END string metadata -------------------------------------
 }
 
 message GetObsResponse {

datastore/storagebackend/postgresql/getobservations.go

@@ -125,7 +125,7 @@ func scanTSRow(rows *sql.Rows) (*datastore.TSMetadata, int64, error) {
 		&linkTitle,
 	}
 
-	// complete colValPtrs with string metadata
+	// complete colValPtrs with string metadata (handleable with reflection)
 	colVals0 := make([]interface{}, len(tsStringMdataGoNames))
 	for i := range tsStringMdataGoNames {
 		colValPtrs = append(colValPtrs, &colVals0[i])
@@ -151,7 +151,7 @@ func scanTSRow(rows *sql.Rows) (*datastore.TSMetadata, int64, error) {
 		Links: links,
 	}
 
-	// complete tsMdata with string metadata
+	// complete tsMdata with string metadata (handleable with reflection)
 	err := addStringMdata(reflect.ValueOf(&tsMdata), tsStringMdataGoNames, colVals0)
 	if err != nil {
 		return nil, -1, fmt.Errorf("addStringMdata() failed: %v", err)
@@ -220,7 +220,7 @@ type stringFilterInfo struct {
 	colName  string
 	patterns []string
 }
-// TODO: add filter infos for non-string types
+// TODO: add filter info for non-string types
 
 // getMdataFilter derives from stringFilterInfos the expression used in a WHERE clause for
 // "match any" filtering on a set of attributes.
@@ -403,7 +403,7 @@ func scanObsRow(rows *sql.Rows) (*datastore.ObsMetadata, int64, error) {
 		&point,
 	}
 
-	// complete colValPtrs with string metadata
+	// complete colValPtrs with string metadata (handleable with reflection)
 	colVals0 := make([]interface{}, len(obsStringMdataGoNames))
 	for i := range obsStringMdataGoNames {
 		colValPtrs = append(colValPtrs, &colVals0[i])
@@ -429,7 +429,7 @@ func scanObsRow(rows *sql.Rows) (*datastore.ObsMetadata, int64, error) {
 		Value: value,
 	}
 
-	// complete obsMdata with string metadata
+	// complete obsMdata with string metadata (handleable with reflection)
 	err := addStringMdata(reflect.ValueOf(&obsMdata), obsStringMdataGoNames, colVals0)
 	if err != nil {
 		return nil, -1, fmt.Errorf("addStringMdata() failed: %v", err)

datastore/storagebackend/postgresql/postgresql.go

@@ -102,7 +102,7 @@ func getTSMdataCols() []string {
 		"link_title",
 	}
 
-	// complete cols with string metadata
+	// complete cols with string metadata (handleable with reflection)
 	cols = append(cols, tsStringMdataPBNames...)
 
 	return cols

datastore/storagebackend/postgresql/putobservations.go

@@ -79,7 +79,7 @@ func getTSColVals(tsMdata *datastore.TSMetadata) ([]interface{}, error) {
 
 	// --- END non-string metadata ---------------------------
 
-	// --- BEGIN string metadata ---------------------------
+	// --- BEGIN string metadata (handleable with reflection) ---------------------------
 
 	rv := reflect.ValueOf(tsMdata)
 	for _, field := range reflect.VisibleFields(reflect.TypeOf(datastore.TSMetadata{})) {

datastore/ts-init.sql

@@ -13,7 +13,7 @@ CREATE TABLE time_series (
 	link_title TEXT[],
 	-- --- END non-string metadata -----------------
 
-	-- --- BEGIN string metadata -----------------
+	-- --- BEGIN string metadata (handleable with reflection) -----------------
     version TEXT NOT NULL, -- required
     type TEXT NOT NULL, -- required
     title TEXT,