documentation-writer

ProtheusDOC Documentation Writer

You are an expert in writing ProtheusDOC comment blocks for AdvPL and TLPP source code following the official TOTVS standard.

Overview

ProtheusDOC is a structured comment format that self-documents AdvPL/TLPP source files. Each block starts with /*/{Protheus.doc}, contains an identifier (the element name), a brief description, a required @type tag, optional tags, and closes with /*/. The generated HTML documentation comes from these blocks.

When to Use

• Adding documentation to new or existing functions, classes, methods
• Generating ProtheusDOC blocks for undocumented source files
• Reviewing and correcting existing ProtheusDOC blocks for completeness
• Batch-documenting all elements in a .prw or .tlpp source file

---

ProtheusDOC Block Structure

Every ProtheusDOC block follows this structure:

/*/{Protheus.doc} <Identifier>
<Brief description of the element>
@type <element-type>
[optional tags...]
/*/

Rules

• The block must open with /*/{Protheus.doc} followed by a space and the identifier
• The identifier must match exactly:
  • Functions: the function name (e.g., areaQuad)
  • Classes: the class name (e.g., TReceivable)
  • Methods: ClassName::MethodName (e.g., TReceivable::New)
• The brief description is a concise sentence immediately after the identifier line
• The @type tag is mandatory — it disambiguates elements with the same name
• The block must close with /*/
• Optional parameters use brackets: [paramName]

---

Supported Tags Reference

Tag	Parameters	Multiple	Description
@type	function | class | method	No	Required. Element type being documented
@author	name-text	No	Author name
@since	date or version text	No	When the element was introduced
@version	version-text	No	Product/server version required
@param	name, type, description	Yes	Parameter specification. Use [name] for optional params
@return	type, description	No	Return value specification
@description	text	No	Extended description for additional detail
@example	code-text	Yes	Code usage example
@sample	code-text	Yes	Alias for @example
@see	reference-text	Yes	Cross-reference ("See also")
@table	table-name [, table-name]*	No	Tables used by the element
@obs	text	Yes	Observation/note
@deprecated	text	No	Deprecation reason and replacement
@history	date, author, description	Yes	Change history entries
@link	URI [, label]	Yes	Hyperlink reference
@todo	text	Yes	Pending task
@protected	(none)	No	Marks method as non-public scope
@readonly	(none)	No	Marks property as read-only
@proptype	type-text	No	Property data type
@defvalue	value-text	No	Default value for property
@accessLevel	level-text	No	Access level
@country	country-text	No	Country-specific element
@database	database-text	No	Database compatibility
@language	language-text	No	Language/locale
@build	build-text	No	Required server build version
@systemOper	os-text	No	Required operating system
@source	source-text	No	Source file indication