Adding Resharper code annotation to own code in a non-invasive manner

Question

I want to flag one of my methods with the StringFormatMethod attribute so Resharper syntax highlights it.

I was able to do this by referencing the JerBrains.Annotations assembly and adding the attribute.

However I find this to be a very invasive way to do this. Not everybody here uses JetBrains and it will require committing the .dll to subversion, adding the dependency and littering the code with something that is specific to a particular IDE, which I hate.

I read about the "external annotations" feature, but I wasn't able to do it. I'm not sure if I did it wrong or if it's simply not supported for a project inside the solution (i.e not a compiled assembly reference).

So is there a way to add a code annotation to a method in the project in a non-invasive way?

P.S this is the method:

using System;

namespace MyLib
{
    public static class Assert
    {
        public static void That(bool condition, string format, params object[] @params)
        {
            if (!condition)
                throw new Exception(string.Format(format, @params));
        }
    }
}

And this is the contents of

C:\Program Files (x86)\JetBrains\ReSharper\v7.1\Bin\ExternalAnnotations\MyLib.xml:

<assembley name="MyLib">
    <member name="MyLib.Assert.That(System.Boolean,System.String,System.Object[])">
        <attribute ctor="M:JetBrains.Annotations.StringFormatMethodAttribute.#ctor">
            <argument>format</argument>
        </attribute>
    </member>
</assembley>

Answer 1

Just to sum up possibilities:

• You reference nuget Jetbrains.Annotations, and DO NOT define JETBRAINS_ANNOTATIONS: Such annotations are useful only for developers working with source code, they are not compiled in your binary (Conditional statement is used) and they are not visible when referencing your dll. You can even add developmentOnly="true" attribute to Jetbrains.Annotations in packages.config, so by default it would not be treated as dependency.

• You reference as above but define JETBRAINS_ANNOTATIONS: now you have real binary dependency and Jetbrains.Annotations.dll must be either distributed with your library or it must be downloaded as nuget dependency.

• You copy annotations with internal checked (so client code would not use them), into "YourLib.Annotations": They then embedded into your lib and available for other developers even when they use only binary version.

• You provide external annotations: for bigger libraries/more attributes this can also consume 40k, it is separate file, and generally it is less trivial to create/consume.

I personally went with third option (for shared libraries, projects usually just use nugets)

Answer 2

You don't have to reference the assembly to add annotation attributes. As per the documentation, you can go to ReSharper/Options/Code Annotations, copy the attribute implementations to the clipboard, and paste them into your own source, where ReSharper will use them. You can even change the namespace they're in if you'd prefer not to have JetBrains in your assembly.

I don't know whether you'll have any luck using external (XML) annotations for source code, though. I get the impression they're only for existing binaries. That said, I think that decorating your source with attributes is quite valuable as a source of documentation for yourself and other developers.

Answer 3

Don't know if it helps, but the element name <assembley> is misspelled (unless they actually used that in the schema). Should be <assembly>.