Add some documentation about naming and reference counting schemes.

3 files changed, 48 insertions, 1 deletions

diff --git a/doc/naming.txt b/doc/naming.txt
new file mode 100644
index 00000000..6c641c33
--- /dev/null
+++ b/doc/naming.txt
@@ -0,0 +1,30 @@
+Functions should be named according to one of the following schemes:
+
+	verb_noun
+	verb_noun_with_noun
+
+	noun_attribute
+	get_noun_attribute -- when the 'noun_attribute' name conflicts with a type
+	set_noun_attribute
+
+Prefixes are mandatory for exported functions, macros, enums, globals and types.
+
+	fz for common code
+	pdf, xps, etc., for interpreter specific code
+
+Prefixes are optional (but encouraged) for private functions and types.
+
+Avoid using 'get' as this is a meaningless and redundant filler word.
+
+These words are reserved for reference counting schemes:
+
+	new, find, load, open, keep -- return objects that you are responsible for freeing.
+
+	drop, free, close -- relinquish ownership of the object passed in.
+
+When searching for an object or value, the name used depends on whether
+returning the value is passing ownership:
+
+	lookup -- return a value or borrowed pointer
+
+	find -- return an object that the caller is responsible for freeing
diff --git a/doc/overview.txt b/doc/overview.txt
index a0074b77..2d4e25d7 100644
--- a/doc/overview.txt
+++ b/doc/overview.txt
@@ -225,7 +225,7 @@ multi-threaded operations run smoothly:
 	document was. This does not mean that the device can only ever
 	be used from one thread, though in many cases this is the
 	simplest structure overall.
-	
+
 So, how does a multi-threaded example differ from a non-multithreaded
 one?
 
diff --git a/doc/refcount.txt b/doc/refcount.txt
new file mode 100644
index 00000000..e575142a
--- /dev/null
+++ b/doc/refcount.txt
@@ -0,0 +1,17 @@
+Reference counting uses special words in functions to make it easy to remember
+and follow the rules.
+
+Words that take ownership: new, find, load, open, keep.
+
+Words that release ownership: drop, free, close.
+
+If an object is returned by a function with one of the special words that take
+ownership, you are responsible for freeing it by calling "drop" or "free", or
+"close" before you return. You may pass ownership of an owned object by return
+it only if you name the function using one of the special words.
+
+Any objects returned by functions that do not have any of these special words,
+are borrowed and have a limited life time. Do not hold on to them past the
+duration of the current function, or stow them away inside structs. If you need
+to keep the object for longer than that, you have to either "keep" it or make
+your own copy.