PasDoc's autodoc

Class TPasItem

Description
Hierarchy
Fields
Methods
Properties

Unit

PasDoc_Items

Declaration

type TPasItem = class(TBaseItem)

Description

This is a TBaseItem descendant that is always declared inside some Pascal source file.

Parser creates only items of this class (e.g. never some basic TBaseItem instance). This class introduces properties and methods pointing to parent unit (MyUnit) and parent class/interface/object/record (MyObject). Also many other things not needed at TBaseItem level are introduced here: things related to handling @abstract tag, @seealso tag, used to sorting items inside (Sort) and some more.

Hierarchy

Overview

Methods

Protected procedure Serialize(const ADestination: TStream); override;
Protected procedure Deserialize(const ASource: TStream); override;
Protected function FindNameWithinUnit(const NameParts: TNameParts): TBaseItem; virtual;
Public constructor Create; override;
Public destructor Destroy; override;
Public function FindName(const NameParts: TNameParts): TBaseItem; override;
Public procedure RegisterTags(TagManager: TTagManager); override;
Public function HasDescription: Boolean;
Public function QualifiedName: String; override;
Public function UnitRelativeQualifiedName: string; virtual;
Public procedure Sort(const SortSettings: TSortSettings); virtual;
Public procedure SetAttributes(var Value: TStringPairVector);
Public function BasePath: string; override;
Public function HasOptionalInfo: boolean; virtual;

Properties

Public property AbstractDescription: string read FAbstractDescription write FAbstractDescription;
Public property AbstractDescriptionWasAutomatic: boolean read FAbstractDescriptionWasAutomatic write FAbstractDescriptionWasAutomatic;
Public property MyUnit: TPasUnit read FMyUnit write FMyUnit;
Public property MyObject: TPasCio read FMyObject write FMyObject;
Public property MyEnum: TPasEnum read FMyEnum write FMyEnum;
Public property Visibility: TVisibility read FVisibility write FVisibility;
Public property HintDirectives: THintDirectives read FHintDirectives write FHintDirectives;
Public property DeprecatedNote: string read FDeprecatedNote write FDeprecatedNote;
Public property FullDeclaration: string read FFullDeclaration write FFullDeclaration;
Public property SeeAlso: TStringPairVector read FSeeAlso;
Public property Attributes: TStringPairVector read FAttributes;
Public property Params: TStringPairVector read FParams;
Public property Raises: TStringPairVector read FRaises;

Description

Methods

Protected procedure Serialize(const ADestination: TStream); override;
 
Protected procedure Deserialize(const ASource: TStream); override;
 
Protected function FindNameWithinUnit(const NameParts: TNameParts): TBaseItem; virtual;

This does the same thing as FindName but it doesn't scan other units. If this item is a unit, it searches only inside this unit, else it searches only inside MyUnit unit.

Actually FindName uses this function.

Public constructor Create; override;
 
Public destructor Destroy; override;
 
Public function FindName(const NameParts: TNameParts): TBaseItem; override;
 
Public procedure RegisterTags(TagManager: TTagManager); override;
 
Public function HasDescription: Boolean;

Returns true if there is a DetailedDescription or AbstractDescription available.

Public function QualifiedName: String; override;
 
Public function UnitRelativeQualifiedName: string; virtual;
 
Public procedure Sort(const SortSettings: TSortSettings); virtual;

This recursively sorts all items inside this item, and all items inside these items, etc. E.g. in case of TPasUnit, this method sorts all variables, consts, CIOs etc. inside (honouring SortSettings), and also recursively calls Sort(SortSettings) for every CIO.

Note that this does not guarantee that absolutely everything inside will be really sorted. Some items may be deliberately left unsorted, e.g. Members of TPasEnum are never sorted (their declared order always matters, so we shouldn't sort them when displaying their documentation — reader of such documentation would be seriously misleaded). Sorting of other things depends on SortSettings — e.g. without ssMethods, CIOs methods will not be sorted.

So actually this method makes sure that all things that should be sorted are really sorted.

Public procedure SetAttributes(var Value: TStringPairVector);
 
Public function BasePath: string; override;
 
Public function HasOptionalInfo: boolean; virtual;

Is optional information (that may be empty for after parsing unit and expanding tags) specified. Currently this checks Params and Raises and TPasMethod.Returns.

Properties

Public property AbstractDescription: string read FAbstractDescription write FAbstractDescription;

Abstract description of this item. This is intended to be short (e.g. one sentence) description of this object.

This will be inited from @abstract tag in RawDescription, or cutted out from first sentence in RawDescription if --auto-abstract was used.

Note that this is already in the form suitable for final output, with tags expanded, chars converted etc.

Public property AbstractDescriptionWasAutomatic: boolean read FAbstractDescriptionWasAutomatic write FAbstractDescriptionWasAutomatic;

TDocGenerator.ExpandDescriptions sets this property to true if AutoAbstract was used and AbstractDescription of this item was automatically deduced from the 1st sentence of RawDescription.

Otherwise (if @abstract was specified explicitly, or there was no @abstract and AutoAbstract was false) this is set to false.

This is a useful hint for generators: it tells them that when they are printing both AbstractDescription and DetailedDescription of the item in one place (e.g. TTexDocGenerator.WriteItemLongDescription and TGenericHTMLDocGenerator.WriteItemLongDescription both do this) then they should not put any additional space between AbstractDescription and DetailedDescription.

This way when user will specify description like 

{ First sentence. Second sentence. }
procedure Foo;

and --auto-abstract was on, then "First sentence." is the AbstractDescription, " Second sentence." is DetailedDescription, AbstractDescriptionWasAutomatic is true and and TGenericHTMLDocGenerator.WriteItemLongDescription can print them as "First sentence. Second sentence."

Without this property, TGenericHTMLDocGenerator.WriteItemLongDescription would not be able to say that this abstract was deduced automatically and would print additional paragraph break that was not present in desscription, i.e. "First sentence.<p> Second sentence."

Public property MyUnit: TPasUnit read FMyUnit write FMyUnit;

Unit of this item.

Public property MyObject: TPasCio read FMyObject write FMyObject;

If this item is part of a class (or record, object., interface...), the corresponding class is stored here. Nil otherwise.

Public property MyEnum: TPasEnum read FMyEnum write FMyEnum;

If this item is a member of an enumerated type, then the enclosing enumerated type is stored here. Nil otherwise.

Public property Visibility: TVisibility read FVisibility write FVisibility;
 
Public property HintDirectives: THintDirectives read FHintDirectives write FHintDirectives;

Hint directives specify is this item deprecated, platform-specific, library-specific, or experimental.

Public property DeprecatedNote: string read FDeprecatedNote write FDeprecatedNote;

Deprecation note, specified as a string after "deprecated" directive. Empty if none, always empty if HintDirectives does not contain hdDeprecated.

Public property FullDeclaration: string read FFullDeclaration write FFullDeclaration;

Full declaration of the item. This is full parsed declaration of the given item.

Note that that this is not used for some descendants. Right now it's used only with

  • TPasConstant

  • TPasFieldVariable (includes type, default values, etc.)

  • TPasType

  • TPasMethod (includes parameter list, procedural directives, etc.)

  • TPasProperty (includes read/write and storage specifiers, etc.)

  • TPasEnum

    But in this special case, '...' is used instead of listing individual members, e.g. 'TEnumName = (...)'. You can get list of Members using TPasEnum.Members. Eventual specifics of each member should be also specified somewhere inside Members items, e.g. 

    TMyEnum = (meOne, meTwo = 3);

    and 

    TMyEnum = (meOne, meTwo);

    will both result in TPasEnum with equal FullDeclaration (just 'TMyEnum = (...)') but this '= 3' should be marked somewhere inside Members[1] properties.

  • TPasItem when it's a CIO's field.

The intention is that in the future all TPasItem descendants will always have approprtate FullDeclaration set. It all requires adjusting appropriate places in PasDoc_Parser to generate appropriate FullDeclaration.

Public property SeeAlso: TStringPairVector read FSeeAlso;

Items here are collected from @seealso tags.

Name of each item is the 1st part of @seealso parameter. Value is the 2nd part of @seealso parameter.

Public property Attributes: TStringPairVector read FAttributes;

List of attributes defined for this item

Public property Params: TStringPairVector read FParams;

Parameters of method or property.

Name of each item is the name of parameter (without any surrounding whitespace), Value of each item is users description for this item (in already-expanded form).

This is already in the form processed by TTagManager.Execute, i.e. with links resolved, html characters escaped etc. So don't convert them (e.g. before writing to the final docs) once again (by some ExpandDescription or ConvertString or anything like that).

Public property Raises: TStringPairVector read FRaises;

Exceptions raised by the method, or by property getter/setter.

Name of each item is the name of exception class (without any surrounding whitespace), Value of each item is users description for this item (in already-expanded form).

This is already in the form processed by TTagManager.Execute, i.e. with links resolved, html characters escaped etc. So don't convert them (e.g. before writing to the final docs) once again (by some ExpandDescription or ConvertString or anything like that).

Generated by PasDoc 0.16.0.