Merge pull request #525 from wking/go-comment-sync

config: Synchronize comments between Markdown and Go

config.md

@@ -10,8 +10,8 @@ Below is a detailed description of each field defined in the configuration forma
 
 ## Specification version
 
-* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OpenContainer specification with which the bundle complies.
-The OpenContainer spec follows semantic versioning and retains forward and backward compatibility within major versions.
+* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies.
+The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
 For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
 
 ### Example
@@ -22,7 +22,7 @@ For example, if an implementation is compliant with version 1.0.1 of the spec, i
 
 ## Root Configuration
 
-Each container has exactly one *root filesystem*, specified in the *root* object:
+**`root`** (object, required) configures the container's root filesystem.
 
 * **`path`** (string, required) Specifies the path to the root filesystem for the container.
   A directory MUST exist at the path declared by the field.
@@ -39,7 +39,7 @@ Each container has exactly one *root filesystem*, specified in the *root* object
 
 ## Mounts
 
-You MAY add array of mount points inside container as `mounts`.
+**`mounts`** (array, optional) configures additional mounts (on top of [`root`](#root-configuration)).
 The runtime MUST mount entries in the listed order.
 The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
 
@@ -90,6 +90,8 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se
 
 ## Process configuration
 
+**`process`** (object, required) configures the container process.
+
 * **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process, defaults to false.
 * **`cwd`** (string, required) is the working directory that will be set for the executable.
   This value MUST be an absolute path.
@@ -189,7 +191,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th
 
 ## Hostname
 
-* **`hostname`** (string, optional) as it is accessible to processes running inside.
+* **`hostname`** (string, optional) configures the container's hostname as seen by processes running inside the container.
   On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
 
 ### Example
@@ -200,6 +202,8 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th
 
 ## Platform
 
+**`platform`** specifies the configuration's target platform.
+
 * **`os`** (string, required) specifies the operating system family this image targets.
   The runtime MUST generate an error if it does not support the configured **`os`**.
   Bundles SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`$GOOS`][go-environment].
@@ -247,6 +251,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th
 
 ## Hooks
 
+**`hooks`** (object, optional) configures callbacks for container lifecycle events.
 Lifecycle hooks allow custom events for different points in a container's runtime.
 Presently there are `Prestart`, `Poststart` and `Poststop`.
 
@@ -317,7 +322,7 @@ The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://g
 
 ## Annotations
 
-This OPTIONAL property contains arbitrary metadata for the container.
+**`annotations`** (object, optional) contains arbitrary metadata for the container.
 This information MAY be structured or unstructured.
 Annotations are key-value maps.
 

runtime.md

@@ -20,7 +20,7 @@ The value MAY be one of:
     * `stopped` : the container has been created and the user-specified code has been executed but is no longer running
 
   Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
-* **`pid`**: (int) is the ID of the main process within the container, as seen by the host.
+* **`pid`**: (int) is the ID of the container process, as seen by the host.
 * **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
 This is provided so that consumers can find the container's configuration and root filesystem on the host.
 * **`annotations`**: (map) contains the list of annotations associated with the container.

schema/config-schema.json

@@ -56,7 +56,7 @@
             }
         },
         "root": {
-            "description": "The path to the root filesystem for the container.",
+            "description": "Configures the container's root filesystem.",
             "id": "https://opencontainers.org/schema/bundle/root",
             "type": "object",
             "properties": {

schema/defs.json

@@ -1,5 +1,5 @@
 {
-    "description": "Definitions used throughout the OpenContainer Specification",
+    "description": "Definitions used throughout the Open Container Runtime Specification",
     "definitions": {
         "int8": {
             "type": "integer",

specs-go/config.go

@@ -4,21 +4,21 @@ import "os"
 
 // Spec is the base configuration for the container.
 type Spec struct {
-	// Version is the version of the specification that is supported.
+	// Version of the Open Container Runtime Specification with which the bundle complies.
 	Version string `json:"ociVersion"`
-	// Platform is the host information for OS and Arch.
+	// Platform specifies the configuration's target platform.
 	Platform Platform `json:"platform"`
-	// Process is the container's main process.
+	// Process configures the container process.
 	Process Process `json:"process"`
-	// Root is the root information for the container's filesystem.
+	// Root configures the container's root filesystem.
 	Root Root `json:"root"`
-	// Hostname is the container's host name.
+	// Hostname configures the container's hostname.
 	Hostname string `json:"hostname,omitempty"`
-	// Mounts profile configuration for adding mounts to the container's filesystem.
+	// Mounts configures additional mounts (on top of Root).
 	Mounts []Mount `json:"mounts,omitempty"`
-	// Hooks are the commands run at various lifecycle events of the container.
+	// Hooks configures callbacks for container lifecycle events.
 	Hooks Hooks `json:"hooks"`
-	// Annotations is an unstructured key value map that may be set by external tools to store and retrieve arbitrary metadata.
+	// Annotations contains arbitrary metadata for the container.
 	Annotations map[string]string `json:"annotations,omitempty"`
 
 	// Linux is platform specific configuration for Linux based containers.
@@ -53,8 +53,8 @@ type Process struct {
 	SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"`
 }
 
-// User specifies Linux/Solaris specific user and group information for the container's
-// main process.
+// User specifies Linux/Solaris specific user and group information
+// for the container process.
 type User struct {
 	// UID is the user id. (this field is platform dependent)
 	UID uint32 `json:"uid" platform:"linux,solaris"`

specs-go/state.go

@@ -8,7 +8,7 @@ type State struct {
 	ID string `json:"id"`
 	// Status is the runtime state of the container.
 	Status string `json:"status"`
-	// Pid is the process id for the container's main process.
+	// Pid is the process ID for the container process.
 	Pid int `json:"pid"`
 	// BundlePath is the path to the container's bundle directory.
 	BundlePath string `json:"bundlePath"`