From d711a5851d5dbd93c68ef45467da06cb07a95a7e Mon Sep 17 00:00:00 2001
From: Eric van der Vlist <vdv@dyomedea.com>
Date: Thu, 29 Apr 2021 14:06:43 +0200
Subject: [PATCH] js-options: doc

---
 oxygen/js-options/README.md | 46 ++++++++++++++++++++++++++++++++++++-
 oxygen/js-options/hello.js  | 10 ++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/oxygen/js-options/README.md b/oxygen/js-options/README.md
index abecc55..84a75a5 100644
--- a/oxygen/js-options/README.md
+++ b/oxygen/js-options/README.md
@@ -1,6 +1,50 @@
-# Options 
+# Options (Work in Progress)
 This rambling shows how to add functionalities to the [OptionStorage](https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/ecss/extensions/api/OptionsStorage.html) mechanism.
 
+## Principle
+
+The idea is to add metadata to be able to do some kind of introspection and cleanup the options store when/if needed.
+
+## Usage [hello.js](hello.js)
+
+Instanciation (with a namespace set to 'hello':
+```javascript
+	var options = new Options(authorAccess, 'hello');
+```
+
+Setting options:
+```javascript
+	var options = new Options(authorAccess, 'hello');
+```
+
+These values can then be retrieved using options.getOption(key, defaultValue) but also as an object:
+```javascript
+	// Retrieve and display these options
+	var myOptions = options.getOptions();
+	for (var key in myOptions) {
+		var value = myOptions[key];
+		Packages.java.lang.System.out.println(key + ' ' + value);
+	}
+```
+
+Options can also be "per file" using methods containing the "SystemId" keyword in their names:
+```javascript
+	// Do the same with file specific options
+	options.setSystemIdOption('Hello', 'aligator');
+	options.setSystemIdOption('See you later', 'World');
+	var myOptions = options.getSystemIdOptions();
+	for (var key in myOptions) {
+		var value = myOptions[key];
+		Packages.java.lang.System.out.println(key + ' ' + value);
+	}
+```
+
+By default, the systemId is the current file system Id but it could be set up to any other file using the setSystemId() method.
+
+Internally, "per file" properties are stored in a namespace which is the concatenation of the options namespace and the SHA1 of the systemId 
+(such as "hello.1D4E43D67658FA9C7F17B230DB629D9DE3FA8001").
+
+
 ## Installation
 
 
diff --git a/oxygen/js-options/hello.js b/oxygen/js-options/hello.js
index 75d00df..79cfbdf 100644
--- a/oxygen/js-options/hello.js
+++ b/oxygen/js-options/hello.js
@@ -1,13 +1,21 @@
 hello = function () {
 	include('options.js');
+	
+	// Instanciation
 	var options = new Options(authorAccess, 'hello');
+	
+	// Set up a couple of options
 	options.setOption('Hello', 'World');
 	options.setOption('See you later', 'aligator');
+	
+	// Retrieve and display these options
 	var myOptions = options.getOptions();
 	for (var key in myOptions) {
 		var value = myOptions[key];
 		Packages.java.lang.System.out.println(key + ' ' + value);
 	}
+	
+	// Do the same with file specific options
 	options.setSystemIdOption('Hello', 'aligator');
 	options.setSystemIdOption('See you later', 'World');
 	var myOptions = options.getSystemIdOptions();
@@ -15,6 +23,8 @@ hello = function () {
 		var value = myOptions[key];
 		Packages.java.lang.System.out.println(key + ' ' + value);
 	}
+	
+	// Display some file specific properties
 	Packages.java.lang.System.out.println('options.systemId: ' + options.systemId);
 	Packages.java.lang.System.out.println('options.systemIdDigest: ' + options.systemIdDigest);
 }
\ No newline at end of file