annotations.md

@@ -93,7 +93,26 @@ The Summer of Code implementation had some drawbacks:
 - Modules must refer to all the packages that contain data structures used in their annotations. This may be a particular problem if you wish to annotate values with things from the GHC package.
 
 
-A better implementation is described in this section.
+A better implementation is described in this section.  The programmer's eye view is largely unchanged: she still declares annotations in the same way.
+
+
+From the point of view of a client of the GHC API or a plugin, the interface looks like this:
+
+```wiki
+-- For normal GHC API users:
+getAnnotations :: (Typeable a, Binary a) => Name -> GHCM [a]
+   -- Get the annotations for an arbitrary Name
+
+getAnnotations :: (Typeable a, Binary a) => Name -> CoreM [a]
+   -- Allows a plugin to get the annotations for any Name
+   -- whether defined locally or imported
+
+putAnnotations :: (Typeable a, Binary a) => Name -> a -> CoreM ()
+   -- Allows a plugin to add its own annotation 
+   -- e.g. the results of an analysis
+   -- The Name must be from the module being compiled; the 
+   -- annotation is persisted into the interface file.
+```
 
 
 When compiling user-declared annotations (i.e. those in the actual text of the program being compiled):
@@ -213,7 +232,13 @@ putAnnotations :: (Typeable a) => (a -> ByteString) -> Name -> a -> CoreM ()
 ```
 
 
-This doesn't require any more packages (we could even remove the ByteString usages here) and it does allow use of multiple different serialization libraries for annotations (should that be desirable). However, this doesn't enforce that the serializer and deserializer for a particular bit of data should be coherent and makes the API a bit unfriendlier.
+This doesn't require any more packages (we could even remove the ByteString usages here) and it does allow use of multiple different serialization libraries for annotations (should that be desirable). However, this makes the API a bit unfriendlier; and (more important) doesn't enforce that the serializer and deserializer for a particular bit of data should be coherent.  For example, the following could easily happen:
+
+- A plugin uses binary-2.1 to serialise stuff into Foo.hi
+- A GHC api client uses binary-3.0 to deserialise it (probably without realising that they are using the "wrong" Binary)
+
+
+Result: extreme broken-ness at run time (not compile time).
 
 ## Future Work