Skip to content

Latest commit

 

History

History
138 lines (114 loc) · 6.13 KB

PX1007.md

File metadata and controls

138 lines (114 loc) · 6.13 KB

PX1007

This document describes the PX1007 diagnostic.

Summary

Code Short Description Type Code Fix
PX1007 The DAC, DAC extension, or DAC property should have a description in the "summary" XML tag or "inheritdoc" XML tag Error Available

Diagnostic Description

Any DAC or DAC extension and their public property fields should have one of the following:

  • A description in the summary XML tag
  • Any number of inheritdoc tags in any format on DACs, DAC extensions, and DAC field properties of non-projection DACs (including unmapped properties of projection DACs). For more details, on the inheritdoc tag, see the inheritdoc tag documentation.
  • The inheritoc XML tag on mapped DAC fields of projection DACs.
  • The exclude tag

The descriptions of the DACs, DAC extensions, and their members can be displayed in the DAC Schema Browser and used for building the API and DAC references for the Acumatica ERP libraries.

Note: For the mapped DAC fields, the original mapped property is determined using one of the following ways:

  • If the field has an attribute with a BqlField property, and this property's value is mapped to a BQL field of an original projection DAC, this BQL field is used for mapping
  • If the field has an attribute with a BqlTable property, and this property's value is the name of the type of the projection DAC, this BQL field is used for mapping The system seaches the mapped field in the specified DAC by its name, so the name of the mapped DAC field should coincide with name of the the projection DAC field.
  • If no BqlField or BqlTable property is available, the system searches for the mapped field among the fields with the same names in the base DACs. The system takes the first such found field.
  • If no fields are found, the field is marked as non-mapped. Non-mapped properties (unbound or calculated at runtime) are processed as normal DAC properties.

The code fix does one of the following:

  • Adds the summary XML tags, in which you type the description of the code item.
  • Adds the exclude XML tag, which excludes the item from the API and DAC references.
  • Adds the inheritdoc tag to a mapped DAC property of a projection DAC. To apply the code fix and add the inheritdoc tag to multiple DACs, you can use the Fix All button in the code fix menu of Visual Studio. Clicking this button will automatically generate correct documentation for most of the projection DAC properties. This code fix also deletes incorrect documentation tags such as summary or other incorrectly declared inheritdoc tags, that should not be placed on the mapped property of a projection DAC.

This diagnostic is intended for Acumatica ERP developers; however, it can be used by any developer to provide documentation of the source code.

Entities for Which the Diagnostic Is Displayed

The diagnostic is currently displayed for the following public entities:

  • DACs
  • DAC extensions
  • DAC property fields

The diagnostic is not displayed for the following items:

  • All members of a public entity if the entity has at least one of the following:
    • The exclude XML tag
    • The PXInternalUseOnly attribute
    • The Obsolete attribute
    • THe PXHidden attribute

      Note: The entity is excluded from documentation if it has the PXHidden attribute.

  • Members of public entities (except nested public types and DAC property fields).
  • Class fields of DACs.
  • The well-known Selected DAC field
  • System fields of DACs, which are the following:
    • CompanyID
    • CompanyMask
    • DeletedDatabaseRecord
    • CreatedByID
    • CreatedByScreenID
    • CreatedDateTime
    • LastModifiedByID
    • LastModifiedByScreenID
    • LastModifiedDateTime
    • TStamp
    • NoteID
    • Attributes
    • GroupMask

To remove a DAC, DAC extension, or DAC property from documentation, instead of suppressing the diagnostic, add the exclude tag.

Enabling the Diagnostic

By default, the PX1007 diagnostic is disabled because most Acuminator users do need to check the presense of XML documentation. To enable the diagnostic, do the following:

  1. In Visual Studio, go to Tools > Options.
  2. In the Options dialog box which opens, go to Acuminator > General.
  3. For the Enable PX1007 diagnostic option, select True.

Example of Code That Results in the Warning

namespace PX.Objects.AR
{
    public class ARReleaseProcess_Extension : PXGraphExtension<ARReleaseProcess> // The PX1007 warning is displayed for this line.
    {
        ...
    }
}

Example of a Code Fix (Added Description)

namespace PX.Objects.AR
{
    /// <summary>
    /// The base document.
    /// </summary>
    public partial class ARDocument : PXBqlTable, IBqlTable
    {
        ...
    }
}

Example of a Code Fix (Excluded Item)

namespace PX.Objects.AR
{
    /// <exclude/>
    public partial class ARDocument : PXBqlTable, IBqlTable
    {
        ...
    }
}

Example of Incorrect Code (No inheritdoc Tag)

The following code is incorrect because it has no inheritdoc tag on a mapped property of a projection DAC.

[Branch(BqlField = typeof(OriginalDac.branchID))]  //Note the BQL expression for property initialization
public virtual Int32? BranchID { get; set; }

Example of a Code Fix (Addition of the inheritdoc Tag)

The following code adds the description of the original DAC field property by using the inheritdoc tag.

/// <inheritdoc cref="OriginalDac.BranchID"/>  
[Branch(BqlField = typeof(OriginalDac.branchID))]  //Note the BqlField property initialization expression
public virtual Int32? BranchID { get; set; }

Related Articles