FOUNDATIONUnder review

AdvPL source documentation and headers

Records contract, dependencies and limitations alongside source.

AdvPL source documentation and headersAdvPL

01 · OVERVIEW

Overview

A useful header explains purpose, input, return and effects; internal comments justify decisions not obvious from statements. Project editorial rules require teaching comments and distinguish document analysis from compilation and execution. Language structure supports comments but does not guarantee that every header format is processed by a tool. The example proposes a plain comment and verifiable contract without claiming automatic documentation-generator compatibility. (USINA.BR, 2026, ref. 1; TOTVS, n.d., ref. 2)

03 · PRACTICAL EXAMPLE

Commented example

#Include "Protheus.ch"
/*
Purpose: double a numeric quantity.
Input: nQuantity, number; return: number or Nil.
Effects: no table or file access.
Protheus validation: pending.
*/
User Function Ed357(nQuantity)
    // Reject invalid types before arithmetic.
    If ValType(nQuantity) <> "N"
        Return Nil
    EndIf
Return nQuantity * 2

Expected result

U_Ed357(3) proposes 6; text proposes Nil, matching the comment. Under review: editorial example neither compiled nor run in Protheus. Check includes, release, RDD and context before testing.

BEST PRACTICES

Update contracts with code; never record credentials in comments.
Under review: editorial example neither compiled nor run in Protheus. Check includes, release, RDD and context before testing.

AdvPL source documentation and headers

Overview

Commented example

Related content

Comments