Skip to content

PX1098.md

Latest commit

 

History

History
108 lines (92 loc) · 4.67 KB

PX1098.md

File metadata and controls

108 lines (92 loc) · 4.67 KB

PX1098

This document describes the PX1098 diagnostic.

Summary

Code Short Description Type Code Fix
PX1098 Methods with the PXOverride attribute must declare an XML documentation comment with a reference to the base method that has the format /// Overrides <seealso cref="{Base method}">. Warning Available

Diagnostic Description

Acumatica best practices for methods with the PXOverride attribute require such methods to have an XML documentation comment with a reference to the base method. The format of the comment is the following: /// Overrides <seealso cref="{Base method}">. This XML comment should not be inside the summary tag or any other XML documentation comment tags because this comment is not a part of method's documentation. A method with the PXOverride attribute can optionally have other XML documentation comments, but the comment with the Overrides reference must be present.

This Acumatica convention ensures that, for a base method declared in a graph or a graph extension, the reference search feature of the IDE can easily find all PXOverride methods that customize the base method. The "Overrides" prefix is used to give developers an opportunity to quickly distinguish the detected PXOverride methods from other references to the base method found by reference search.

Further Constraints of Methods with the PXOverride Attribute

  • The overriding method must be declared in a graph extension.
  • The overriding method should not be static.
  • The overriding method must have the public access modifier.
  • The overriding method cannot be virtual, abstract, or override.
  • The overriding method cannot be a generic method.
  • The signature of the overriding method must be compatible with the signature of the overridden base method. The names of the derived method and the base method must match.
  • The overriding method should always declare an additional delegate parameter.
  • The base method must be virtual (have either virtual or override modifiers).
  • The base method must have one of the following accessibility levels: public, protected, or protected internal.

Code Fix

The code fix for the PX1098 diagnostic will generate a missing XML documentation comment with a reference to the base method in the required format. Like many other Acuminator code fixes, this code fix can be used for the entire solution or project to quickly address all places with missing XML comments for methods with the PXOverride attribute.

Example of Correct Code

The following example demonstrates the correct declaration of the PXOverride method.

public class MyGraph : PXGraph<MyGraph>
{
}

public class BaseGraphExtension : PXGraphExtension<MyGraph>
{
	public virtual int Add(int x, string y)
	{
		return x + Convert.ToInt32(y);
	}
}

public class DerivedGraphExtension : PXGraphExtension<BaseGraphExtension, MyGraph>
{
	/// Overrides <seealso cref="BaseGraphExtension.Add(int, string)"/>
	[PXOverride]
	public int Add(int x, string y, Func<int, string, int> base_Add)
	{
		if (x < 10)
		{
			return x + Convert.ToInt32(y) * 2;
		}
		return base_Add(x, y);
	}
}

Example of Incorrect Code

In the following example, the PXOverride methods do not have the XML doc comments with a reference to the base method in the required format.

public class MyGraph : PXGraph<MyGraph>
{
	protected virtual void UpdateBalances()
	{
		// Implementation
	}
}

public class BaseGraphExtension : PXGraphExtension<MyGraph>
{
	public virtual int Add(int x, string y)
	{
		return x + Convert.ToInt32(y);
	}
}

public class DerivedGraphExtension : PXGraphExtension<BaseGraphExtension, MyGraph>
{
	[PXOverride]
	public int Add(int x, string y, Func<int, string, int> base_Add)
	{
		if (x < 10)
		{
			return x + Convert.ToInt32(y) * 2;
		}

		return base_Add(x, y);
	}

	[PXOverride]
	protected void UpdateBalances(Action base_UpdateBalances)
	{
		base_UpdateBalances();

		// Implementation
	}
}

Related Articles