Updated example to show how to populate comment section, solves #11

tests/usage_examples/create_ffi1001.py

@@ -12,6 +12,7 @@ ict.PIName = "Knote, Christoph"
 ict.PIAffiliation = "Faculty of Medicine, University Augsburg, Germany"
 ict.dataSourceDescription = "Example data"
 ict.missionName = "MBEES"
+# to simplify dates and avoid time zone issues, these dates are simple 3 item lists [YYYY, MM, DD]
 ict.dateOfCollection = datetime.datetime.utcnow().timetuple()[:3]
 ict.dateOfRevision = datetime.datetime.utcnow().timetuple()[:3]
 
@@ -40,14 +41,42 @@ ict.dependentVariables["Payload"] = icartt.Variable(
     "Payload", "some_units", "Payload", "Payload", scale=1.0, miss=-9999999
 )
 
+# Normal and Special Comments
+
+# note: all comments can be multi-line per standard.
+# To ensure portability the decision was made to represent them as lists,
+# with each list item representing a line.
+
+# E.g., Special Comments are simple lists, which we can append to:
 ict.specialComments.append("Some comments on this dataset:")
 ict.specialComments.append("They are just examples!")
 ict.specialComments.append("Adapt as needed.")
 
+# Normal Comments are separated into freeform and (required) keyword comments.
+
+# Freeform comments are, just like special comments, a list with one line per entry
 ict.normalComments.freeform.append("free comment line 1")
 ict.normalComments.freeform.append("free comment line 2")
 
-# ict.normalComments are all set to N/A if not specified
+# Keywords are mandatory, all need to exist, and default to N/A
+# they can be set as follows:
+ict.normalComments.keywords["PI_CONTACT_INFO"].append(
+    "Christoph Knote, MBEES, Faculty of Medicine, University Augsburg, Augsburg, Germany"
+)
+ict.normalComments.keywords["PI_CONTACT_INFO"].append(
+    "christoph.knote@med.uni-augsburg.de"
+)
+ict.normalComments.keywords["PLATFORM"].append("ICARTT")
+ict.normalComments.keywords["PROJECT_INFO"].append(
+    "A format reader/writer for ICARTT files"
+)
+# ... and so forth
+
+# note for revisions: we assume you take care of the required documentation of past versions
+# and setting the correct date for the current revision (ict.dateOfRevision, see above)
+ict.normalComments.keywords["REVISION"].append("R1")
+ict.normalComments.keywords["REVISION"].append("R1: current status")
+ict.normalComments.keywords["REVISION"].append("R0: early beta")
 
 ict.endDefineMode()
 
@@ -60,7 +89,7 @@ ict.endDefineMode()
 import numpy as np
 
 #                 ivar  dvar1 dvar2
-data = np.array([(15.4, 15.0, 52452495290e5)])
+data = np.array([(15.4, 15.0, 5.24524952903484e5)])
 ict.data.add(data)
 
 # Note 1: you are responsible to ensure that the order of elements in a data line
@@ -71,7 +100,7 @@ print([x for x in ict.variables])
 
 # Note 3: multiple data lines can be added in bulk!
 #                 ivar  dvar1 dvar2       ivar  dvar1 dvar2      ...
-data = np.array([(13.4, 14.0, 2348925e5), (14.1, 14.9, 23425634e5)])
+data = np.array([(13.4, 14.0, 2.348925e5), (14.1, 14.9, 2.3425634e5)])
 
 ict.data.add(data)