Class TPasItem

Description
Hierarchy
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.

Source: source/component/PasDoc_Items.pas (line 358).

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 InheritedItem: TPasItem; virtual;
Public function GetInheritedItemDescriptions: TStringPairVector; virtual;
Public function BasePath: string; override;
Public function HasOptionalInfo: boolean; virtual;
Public function IsOverride: 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;
Public property SourceAbsoluteFileName: string read FSourceAbsoluteFileName write FSourceAbsoluteFileName;
Public property SourceLine: Integer read FSourceLine write FSourceLine;

Description

Methods

Protected procedure Serialize(const ADestination: TStream); override;

This item has no description. Showing description inherited from TBaseItem.Serialize.

Serialization of TPasItem need to store in stream only data that is generated by parser. That's because current approach treats "loading from cache" as equivalent to parsing a unit and stores to cache right after parsing a unit. So what is generated by parser must be written to cache.

That said,

  1. It will not break anything if you will accidentally store in cache something that is not generated by parser. That's because saving to cache will be done anyway right after doing parsing, so properties not initialized by parser will have their initial values anyway. You're just wasting memory for cache, and some cache saving/loading time.

  2. For now, in implementation of serialize/deserialize we try to add even things not generated by parser in a commented out code. This way if approach to cache will change some day, we will be able to use this code.

Source: source/component/PasDoc_Items.pas (line 394).

Protected procedure Deserialize(const ASource: TStream); override;

This item has no description.

Source: source/component/PasDoc_Items.pas (line 395).

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.

Source: source/component/PasDoc_Items.pas (line 403).

Public constructor Create; override;

This item has no description.

Source: source/component/PasDoc_Items.pas (line 405).

Public destructor Destroy; override;

This item has no description.

Source: source/component/PasDoc_Items.pas (line 406).

Public function FindName(const NameParts: TNameParts): TBaseItem; override;

This item has no description. Showing description inherited from TBaseItem.FindName.

Do all you can to find link specified by NameParts.

While searching this tries to mimic ObjectPascal identifier scope as much as it can. It seaches within this item, but also within class enclosing this item, within ancestors of this class, within unit enclosing this item, then within units used by unit of this item.

Source: source/component/PasDoc_Items.pas (line 408).

Public procedure RegisterTags(TagManager: TTagManager); override;

This item has no description. Showing description inherited from TBaseItem.RegisterTags.

It registers TTags that init Authors, Created, LastMod and remove relevant tags from description. You can override it to add more handlers.

Source: source/component/PasDoc_Items.pas (line 410).

Public function HasDescription: Boolean;

Returns true if there is a DetailedDescription or AbstractDescription available.

Source: source/component/PasDoc_Items.pas (line 465).

Public function QualifiedName: String; override;

This item has no description. Showing description inherited from TBaseItem.QualifiedName.

Returns the qualified name of the item. This is intended to return a concise and not ambigous name. E.g. in case of TPasItem it is overridden to return Name qualified by class name and unit name.

In this class this simply returns Name.

Source: source/component/PasDoc_Items.pas (line 467).

Public function UnitRelativeQualifiedName: string; virtual;

This item has no description.

Source: source/component/PasDoc_Items.pas (line 468).

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.

Source: source/component/PasDoc_Items.pas (line 510).

Public procedure SetAttributes(var Value: TStringPairVector);

This item has no description.

Source: source/component/PasDoc_Items.pas (line 553).

Public function InheritedItem: TPasItem; virtual;

Get the closest item that this item inherits from.

Source: source/component/PasDoc_Items.pas (line 556).

Public function GetInheritedItemDescriptions: TStringPairVector; virtual;

Generate a list of descriptions defined on this item in base classes.

This stops at the first class ancestor to have a description defined for an ancestor of this item. Along the way it will also collect descriptions of this item from any implemented interfaces.

If there is no description in any ancestor, it will return an empty vector.

Source: source/component/PasDoc_Items.pas (line 565).

Public function BasePath: string; override;

This item has no description. Showing description inherited from TBaseItem.BasePath.

The full (absolute) path used to resolve filenames in this item's descriptions. Must always end with PathDelim. In this class, this simply returns GetCurrentDir (with PathDelim added if needed).

Source: source/component/PasDoc_Items.pas (line 567).

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 TPasRoutine.Returns.

Source: source/component/PasDoc_Items.pas (line 599).

Public function IsOverride: Boolean; virtual;

Whether this item overrides an item in an ancestor.

Source: source/component/PasDoc_Items.pas (line 602).

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.

Source: source/component/PasDoc_Items.pas (line 422).

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."

Source: source/component/PasDoc_Items.pas (line 459).

Public property MyUnit: TPasUnit read FMyUnit write FMyUnit;

Unit of this item.

Source: source/component/PasDoc_Items.pas (line 471).

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.

Source: source/component/PasDoc_Items.pas (line 475).

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.

Source: source/component/PasDoc_Items.pas (line 479).

Public property Visibility: TVisibility read FVisibility write FVisibility;

This item has no description.

Source: source/component/PasDoc_Items.pas (line 481).

Public property HintDirectives: THintDirectives read FHintDirectives write FHintDirectives;

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

Source: source/component/PasDoc_Items.pas (line 485).

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.

Source: source/component/PasDoc_Items.pas (line 490).

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

  • TPasRoutine (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.

Source: source/component/PasDoc_Items.pas (line 543).

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.

Source: source/component/PasDoc_Items.pas (line 549).

Public property Attributes: TStringPairVector read FAttributes;

List of attributes defined for this item

Source: source/component/PasDoc_Items.pas (line 552).

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).

Source: source/component/PasDoc_Items.pas (line 580).

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).

Source: source/component/PasDoc_Items.pas (line 593).

Public property SourceAbsoluteFileName: string read FSourceAbsoluteFileName write FSourceAbsoluteFileName;

Source (absolute) file name where this item is declared. Set by the parser when parsing the item's declaration.

Source: source/component/PasDoc_Items.pas (line 606).

Public property SourceLine: Integer read FSourceLine write FSourceLine;

Source line number (1-based) where this item is declared. Set by the parser when parsing the item's declaration.

Source: source/component/PasDoc_Items.pas (line 611).

Generated by PasDoc 0.17.0.snapshot.