ERP Documentation Conventions

These conventions apply when adding or updating YARD documentation in Ruby source files.

Format

Primary format: YARD tags + Markdown descriptions.
Use @param, @return, @raise, @see, and @note tags.
Write all prose in Markdown (the project uses commonmarker as the YARD markup provider).

Database Types

Reference the annotate_rb comments at the top of each model file for column names, types, and defaults.
When db/structure.sql is loaded as context, use it to determine correct column types for @return and @param tags (e.g., [BigDecimal] for numeric, [String] for character varying, [Boolean] for boolean).
JSONB columns documented with jsonb_accessor should use the declared Ruby type, not [Hash].

Method Documentation

Document every public method with:

A one-line Markdown summary.
@param [Type] name description for every argument.
@return [Type] description for the return value.
@raise [ErrorType] if the method raises specific exceptions.

Use specific return types, not generic ones:

Use this	Not this
`[Array<Order>]`	`[Array]`
`[ActiveRecord::Relation]`	`[Object]`
`[Boolean]`	`[TrueClass]`
`[BigDecimal]`	`[Numeric]`
`[Customer, nil]`	`[Object]`

Example

# Recalculates tier-2 pricing for all open line items.
#
# @param customer [Customer] the customer whose pricing is being recalculated
# @param effective_date [Date] date from which new pricing takes effect
# @return [Array<LineItem>] line items that were updated
# @raise [Credit::InsufficientFundsError] if the customer's credit is exhausted
def recalculate_pricing(customer, effective_date)

Business Logic

If a method contains ERP math, regulatory logic, or non-obvious business rules, add a ### Logic Details Markdown header inside the docstring. Use @note for edge cases.

# Determines the discount tier for a given order total.
#
# ### Logic Details
# Tier 1 applies at $5,000+ (contractual threshold per MSA section 4.2).
# Tier 2 applies at $15,000+ but only for customers with annual revenue > $100K.
# Tax-exempt items are excluded from the total before tier evaluation.
#
# @note Orders with mixed tax classes use the highest applicable tier.
#
# @param order [Order] the order to evaluate
# @return [Integer] tier level (0, 1, or 2)
def discount_tier(order)

Class-Level Documentation

Each class must have a top-level comment block explaining its role in the ERP system. Include @see tags linking to related service objects or endpoints.

# Attempts to automatically increase a customer's available credit.
#
# Runs eligibility evaluation, and either approves (bumps credit, lifts hold,
# emails accounting) or denies (routes for manual review).
#
# @see Credit::EligibilityEvaluator
# @see InternalMailer#auto_credit_increase_notification
module Credit
  class AutoIncrease

Tag Order

When a method has multiple tags, use this order:

@param
@option
@return
@raise
@see
@example
@note

Concerns and Modules

Methods inside included do ... end blocks are public instance methods -- document them the same way.
Methods inside class_methods do ... end blocks are class methods -- document with @return on self. semantics.
State machine definitions (state_machine) auto-generate events and states -- add a class-level @see to the model for the state diagram.

What NOT to Do

Do not add comments that just narrate what the code does ("increments the counter", "returns the result").
Do not document private methods unless they contain critical business logic.
Do not use [Object] or [Hash] when a more specific type is known.
Do not invent types -- if unsure, check db/structure.sql or the annotate_rb header.