PasDoc's autodoc

Class TBaseItem

Description
Hierarchy
Fields
Methods
Properties

Unit

PasDoc_Items

Declaration

type TBaseItem = class(TSerializable)

Description

This is a basic item class, that is linkable, and has some RawDescription.

Hierarchy

Overview

Methods

Protected procedure Serialize(const ADestination: TStream); override;
Protected procedure Deserialize(const ASource: TStream); override;
Public constructor Create; override;
Public destructor Destroy; override;
Public procedure RegisterTags(TagManager: TTagManager); virtual;
Public function FindItem(const ItemName: string): TBaseItem; virtual;
Public function FindItemMaybeInAncestors(const ItemName: string): TBaseItem; virtual;
Public function FindName(const NameParts: TNameParts): TBaseItem; virtual;
Public function RawDescriptionInfo: PRawDescriptionInfo;
Public function QualifiedName: String; virtual;
Public function BasePath: string; virtual;

Properties

Public property DetailedDescription: string read FDetailedDescription write FDetailedDescription;
Public property RawDescription: string read GetRawDescription write WriteRawDescription;
Public property FullLink: string read FFullLink write FFullLink;
Public property LastMod: string read FLastMod write FLastMod;
Public property Name: string read FName write FName;
Public property Authors: TStringVector read FAuthors write SetAuthors;
Public property Created: string read FCreated;
Public property AutoLinkHereAllowed: boolean read FAutoLinkHereAllowed write FAutoLinkHereAllowed default true;

Description

Methods

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

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.

Protected procedure Deserialize(const ASource: TStream); override;
 
Public constructor Create; override;
 
Public destructor Destroy; override;
 
Public procedure RegisterTags(TagManager: TTagManager); virtual;

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

Public function FindItem(const ItemName: string): TBaseItem; virtual;

Search for an item called ItemName inside this Pascal item. For units, it searches for items declared inside this unit (like a procedure, or a class in this unit). For classes it searches for items declared within this class (like a method or a property). For an enumerated type, it searches for members of this enumerated type.

All normal rules of ObjectPascal scope apply, which means that e.g. if this item is a unit, FindItem searches for a class named ItemName but it doesn't search for a method named ItemName inside some class of this unit. Just like in ObjectPascal the scope of identifiers declared within the class always stays within the class. Of course, in ObjectPascal you can qualify a method name with a class name, and you can also do such qualified links in pasdoc, but this is not handled by this routine (see FindName instead).

Returns nil if not found.

Note that it never compares ItemName with Self.Name. You may want to check this yourself if you want.

Note that for TPasItem descendants, it always returns also some TPasItem descendant (so if you use this method with some TPasItem instance, you can safely cast result of this method to TPasItem).

Implementation in this class always returns nil. Override as necessary.

Public function FindItemMaybeInAncestors(const ItemName: string): TBaseItem; virtual;

This is just like FindItem, but in case of classes or such it should also search within ancestors. In this class, the default implementation just calls FindItem.

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

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.

Public function RawDescriptionInfo: PRawDescriptionInfo;

Full info about RawDescription of this item, including it's filename and position.

This is intended to be initialized by parser.

This returns PRawDescriptionInfo instead of just TRawDescriptionInfo to allow natural setting of properties of this record (otherwise 

Item.RawDescriptionInfo.StreamName := 'foo';

would not work as expected) .

Public function QualifiedName: String; virtual;

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.

Public function BasePath: string; virtual;

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

Properties

Public property DetailedDescription: string read FDetailedDescription write FDetailedDescription;

Detailed description of this item.

In case of TPasItem, this is something more elaborate than TPasItem.AbstractDescription.

This is already in the form suitable for final output, ready to be put inside final documentation.

Public property RawDescription: string read GetRawDescription write WriteRawDescription;

This stores unexpanded version (as specified in user's comment in source code of parsed units) of description of this item.

Actually, this is just a shortcut to RawDescriptionInfo.Content

Public property FullLink: string read FFullLink write FFullLink;

a full link that should be enough to link this item from anywhere else

Public property LastMod: string read FLastMod write FLastMod;

Contains '' or string with date of last modification. This string is already in the form suitable for final output format (i.e. already processed by TDocGenerator.ConvertString).

Public property Name: string read FName write FName;

name of the item

Public property Authors: TStringVector read FAuthors write SetAuthors;

list of strings, each representing one author of this item

Public property Created: string read FCreated;

Contains '' or string with date of creation. This string is already in the form suitable for final output format (i.e. already processed by TDocGenerator.ConvertString).

Public property AutoLinkHereAllowed: boolean read FAutoLinkHereAllowed write FAutoLinkHereAllowed default true;

Is auto-link mechanism allowed to create link to this item ? This may be set to False by @noAutoLinkHere tag in item's description.

Generated by PasDoc 0.16.0.