Add documentation about features relating to layers.

Fixes #36.

doc/reading.md

@@ -145,6 +145,10 @@ If you know the ID of a feature you can get the feature using
 all the features in the layer, decoding each one until it finds the right ID.
 This is almost always **not** what you want.
 
+Note that the feature returned by `next_feature()` or `get_feature_by_id()`
+will internally contain a pointer to the layer it came from. The layer has to
+stay valid as long as the feature is used.
+
 ## The feature
 
 You get features from the layer as described in the previous chapter. The

include/vtzero/feature.hpp

@@ -34,6 +34,9 @@ namespace vtzero {
 
     /**
      * A feature according to spec 4.2.
+     *
+     * Note that a feature will internally contain a pointer to the layer it
+     * came from. The layer has to stay valid as long as the feature is used.
      */
     class feature {
 

include/vtzero/layer.hpp

@@ -297,6 +297,10 @@ namespace vtzero {
         /**
          * Get the next feature in this layer.
          *
+         * Note that the feature returned will internally contain a pointer to
+         * the layer it came from. The layer has to stay valid as long as the
+         * feature is used.
+         *
          * Complexity: Constant.
          *
          * @returns The next feature or the invalid feature if there are no
@@ -357,6 +361,10 @@ namespace vtzero {
          * Get the feature with the specified ID. If there are several features
          * with the same ID, it is undefined which one you'll get.
          *
+         * Note that the feature returned will internally contain a pointer to
+         * the layer it came from. The layer has to stay valid as long as the
+         * feature is used.
+         *
          * Complexity: Linear in the number of features.
          *
          * @param id The ID to look for.