add some docs

dlib/serialize.h

@@ -136,6 +136,46 @@
         then serialize the exponent and mantissa values using dlib's integral serialization
         format.  Therefore, the output is first the exponent and then the mantissa.  Note that
         the mantissa is a signed integer (i.e. there is not a separate sign bit).
+
+
+    MAKING YOUR OWN CUSTOM OBJECTS SERIALIZABLE
+        Suppose you create your own type, my_custom_type, and you want it to be serializable.  I.e.
+        you want to be able to use the tools above to save and load it.  E.g. maybe you have a
+        std::vector<my_custom_type> you wish to save.
+
+        To make my_custom_type properly serializable all you have to do is define global serialize
+        and deserialize functions **IN THE SAME NAMESPACE AS MY_CUSTOM_TYPE**.  You must define them
+        in your namespace so that argument dependent lookup will be able to find them.  So your code
+        might look like this:
+
+            namespace your_namespace 
+            {
+                struct my_custom_type
+                {
+                    int a;
+                    float b;
+                    std::vector<float> c;
+                };
+                void serialize (const my_custom_type& item, std::ostream& out);
+                void deserialize (my_custom_type& item, std::istream& in);
+            }
+       
+        That's all you need to do.  You may optionally avail yourself of the
+        DLIB_DEFINE_DEFAULT_SERIALIZATION macro, which generates global friend serialize and
+        deserialize functions for you.  In that case you would do this instead:
+
+            namespace your_namespace 
+            {
+                struct my_custom_type
+                {
+                    int a;
+                    float b;
+                    std::vector<float> c;
+
+                    DLIB_DEFINE_DEFAULT_SERIALIZATION(my_custom_type, a, b, c);
+                };
+            }
+
 !*/
 
 
@@ -1808,6 +1848,10 @@ namespace dlib
         using dlib::serialize_these;                                    \
         try                                                             \
         {                                                               \
+            /* Write a version header so that if, at a later time, */   \
+            /* you realize you need to change the serialization    */   \
+            /* format you can identify which version of the format */   \
+            /* you are encountering when reading old files.        */   \
             int version = 1;                                            \
             serialize(version, out);                                    \
             serialize_these(out, __VA_ARGS__);                          \