full docs for external annotation

Where are the current docs for the external annotations feature for ReSharper 7 (and in case there is something new, for ReSharper 8)? I am looking for

  • a complete list of all possible types of annotations,
  • how to use them in XML, i.e. the format and the availibale elements of the XML (maybe there is an XSD?)  
  • how to install/deploy external annotations, i.e. what are valid places to put the annotations (can I put the files anywhere else but in %ResharperInstallDir%\Bin\ExternalAnnotations, maybe user scope or solution scope or on a server?)
1 comment

Here's the documentation for extenal annotations: http://www.jetbrains.com/resharper/webhelp/Code_Analysis__External_Annotations.html

It provides an explanation of the xml format (it's just the same as .net's xml docs), and what should be put in there. ReSharper also has a "copy as xml doc id" menu item that makes it a little easier to get the names right. This is available by default in ReSharper 8, but you need to enable "internal mode" to get this with ReSharper 7 - see here: http://hadihariri.com/2009/06/26/resharpers-hidden-gem/

The best way to get a complete list of annotations is to get a copy of the source, which you can do from the annotations page in the options dialog. This will copy the code to the clipboard and you can paste that into a text file/editor to see what's going on. They come with xml documentation. It should also be noted that external annotations are actually just a way of applying attributes to already compiled code. You can use any attributes you want, so it's also possible to mark a type member as obsolete without recompiling: http://hmemcpy.com/2013/03/even-more-resharper-annotations-hackery-marking-3rd-party-code-as-obsolete/

Distributing annotations is easy in ReSharper 8 - they can be packaged up in an extension's nuget package (http://confluence.jetbrains.com/display/NETCOM/1.9+Packaging+%28R8%29). But it's a little trickier for ReSharper 7, where you need to put the files either in the install dir (bin\ExternalAnnotations), or in the same folder as the dll it's for. You can be a bit cheeky and work around this with a plugin that sets an internal field by reflection, but if more than one plugin wants to set this, it's best they set it to the same location, or things will go wrong. You can see how it works here: http://xunitcontrib.codeplex.com/SourceControl/latest#resharper/src/xunitcontrib.runner.resharper.provider/Annotations/AnnotationsLoaderHack.cs


Please sign in to leave a comment.