diff --git a/src/Annotations.cs b/src/Annotations.cs index 388debf..0af1744 100644 --- a/src/Annotations.cs +++ b/src/Annotations.cs @@ -646,6 +646,55 @@ public MustUseReturnValueAttribute([NotNull] string justification) [CanBeNull] public string Justification { get; } } + /// + /// Indicates that the resulting resource of the constructor or method invocation must be disposed after use. + /// + /// + /// Annotating input parameters with this attribute is meaningless.
+ /// Constructors inherit this attribute from their class, if it is decorated.
+ /// Because of attribute inheritance, you should explicitly decorate constructors which are + /// calling base constructor that is already decorated with this attribute.
+ /// Disposing is expected to be performed via either using (resource) statement, using var declaration, + /// or call to a method with kind of decoration, + /// usually IDisposable.Dispose() implementation. + ///
+ [AttributeUsage( + AttributeTargets.Class | AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Parameter)] + [Conditional("JETBRAINS_ANNOTATIONS")] + public sealed class MustDisposeResourceAttribute : Attribute + { + public MustDisposeResourceAttribute() + { + Value = true; + } + + /// + public MustDisposeResourceAttribute(bool value) + { + Value = value; + } + + /// + /// When set to false, disposing of the resource is not obligatory and will be performed during garbage collection. + /// The main use-case for explicit [MustDisposeResource(false)] annotation is to loosen inherited annotation. + /// + public bool Value { get; } + } + + /// + /// Indicates that method or class instance acquires resource ownership and will dispose it after use. + /// + /// + /// Decorating an out parameter with this attribute is meaningless.
+ /// When a method itself is decorated with this attribute, its call disposes instance resource.
+ /// When a field or a property is decorated with this attribute, it shows that this class owns the resource in it + /// and will dispose it properly (e.g. in own Dispose method). + ///
+ [AttributeUsage( + AttributeTargets.Method | AttributeTargets.Parameter | AttributeTargets.Field | AttributeTargets.Property)] + [Conditional("JETBRAINS_ANNOTATIONS")] + public sealed class HandlesResourceDisposalAttribute : Attribute { } + /// /// This annotation allows to enforce allocation-less usage patterns of delegates for performance-critical APIs. /// When this annotation is applied to the parameter of delegate type, the IDE checks the input argument of this parameter: