Package com._1c.g5.v8.dt.bsl.documentation.comment

Class BslDocumentationComment

java.lang.Object

com._1c.g5.v8.dt.bsl.documentation.comment.BslDocumentationComment

All Implemented Interfaces:

IDescriptionPart

public class BslDocumentationComment
extends Object
implements IDescriptionPart

Class represents the Bsl documentation comment as in new format and in old format. Common description of the documentation comment is:

 //(Deprecated. | Устарела)? Description
 //(Parameters: | Параметры:)
 //* parameterName1 ((type section description) | (text description))
 //...
 //* parameterNameN ((type section description) | (text description))
 //(Call options: | Варианты вызова:)
 //text description of the method call options
 //(Returns: | Возвращаемое значение:)
 //((type section description) | (text description))
 //(Example: | Пример:)
 //text description of the example of using method
 

Class BslDocumentationComment.Section corresponding to the each part of comment. Parameters section has special section BslDocumentationComment.ParametersSection. Return section has special section BslDocumentationComment.ReturnSection. Text part description represents by IDescriptionPart. Type section part represents by TypeSection. Differences between old and new format is little:

• keywords "Returns:" replaced to "Return value" in old format
• there is no "*" before parameterName in oldFormat
• differences in type section description - see TypeSection

All keyword of the format in IBslCommentToken

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	BslDocumentationComment.Description	Class represent description of the BslDocumentationComment.Section of the Bsl documentation comment.
static class	BslDocumentationComment.ParametersSection	Class represents parameter section of the Bsl documentation comment.
static class	BslDocumentationComment.ReturnSection	Class represents return section of the Bsl documentation comment.
static class	BslDocumentationComment.Section	Class represents section of the Bsl documentation comment.

Constructor Summary

Constructors

Constructor	Description
BslDocumentationComment()	Empty constructor
BslDocumentationComment(BslContextDefMethod method)	Constructor by BslContextDefMethod
BslDocumentationComment(Module module, Method method, int[] lineLocalOffsets)	Constructor

Method Summary

Modifier and Type	Method	Description
Collection<TypeItem>	computeParameterTypes(String name, org.eclipse.xtext.scoping.IScope typeScope, org.eclipse.xtext.scoping.IScopeProvider scopeProvider, org.eclipse.xtext.naming.IQualifiedNameConverter qualifiedNameConverter, BslMultiLineCommentDocumentationProvider commentProvider, IV8ProjectManager v8ProjectManager, boolean oldFormat, org.eclipse.emf.ecore.EObject context, BmOperationContext typeComputationContext)	Computes real types for parameter from ParameterSection
Collection<TypeItem>	computeReturnTypes(org.eclipse.xtext.scoping.IScope typeScope, org.eclipse.xtext.scoping.IScopeProvider scopeProvider, org.eclipse.xtext.naming.IQualifiedNameConverter qualifiedNameConverter, BslMultiLineCommentDocumentationProvider commentProvider, IV8ProjectManager v8ProjectManager, boolean oldFormat, org.eclipse.emf.ecore.EObject context, BmOperationContext typeComputationContext)	Computes real types for BslDocumentationComment.ReturnSection
BslDocumentationComment.Section	getCallOptionsSection()	Gets the actual description of the call options BslDocumentationComment.Section
BslDocumentationComment.Section	getCommentSection(int lineNumber)	Gets actual documentation comment BslDocumentationComment.Section by line number
BslDocumentationComment.Description	getDescription()	Gets the main comment BslDocumentationComment.Description
IDescriptionPart	getDescriptionPart(int lineNumber, int offset)	Gets actual documentation comment IDescriptionPart by line number and local line offset
BslDocumentationComment.Section	getExampleSection()	Gets the actual description of the example BslDocumentationComment.Section
int[]	getLineGlobalOffsets()	Gets the offsets of the each line in comment relatively to the total method text, cannot be null
int	getLineNumber()	Gets the line nubmer corresponding to part.
Method	getMethod()	Gets the method Method of the documentation comment
Module	getModule()	Gets the module Module of the documentation comment
int	getOffset()	Gets offset of the begining part.
BslDocumentationComment.ParametersSection	getParametersSection()	Gets the actual description of the BslDocumentationComment.ParametersSection
IDescriptionPart	getParent()	Gets the parent object.
BslDocumentationComment.ReturnSection	getReturnSection()	Gets the actual description of the BslDocumentationComment.ReturnSection
boolean	isDeprecated()	Checks that special keyword for marking method as deprecated found
boolean	match(int lineNumber, int offset)	Checks that this description part corresponding to the concrete line number and offset
void	parse(List<String> templateLines, List<String> paramNames)	Parses comment lines corresponding to the new documentation format
void	parseOldFormat(List<String> templateLines, List<String> paramNames)	Parses comment lines corresponding to the old documentation format
void	setCallOptionsSection(BslDocumentationComment.Section callOptionsSection)	Sets new call options BslDocumentationComment.Section
void	setDeprecated(boolean deprecated)	Sets that documentation comment corresponding to the deprecated method
void	setDescription(BslDocumentationComment.Description description)	Sets the main comment BslDocumentationComment.Description
void	setExampleSection(BslDocumentationComment.Section exampleSection)	Sets new example BslDocumentationComment.Section
void	setParametersSection(BslDocumentationComment.ParametersSection parametersSection)	Sets new BslDocumentationComment.ParametersSection
void	setReturnSection(BslDocumentationComment.ReturnSection returnSection)	Sets new BslDocumentationComment.ReturnSection

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

BslDocumentationComment

public BslDocumentationComment()

Empty constructor

BslDocumentationComment

public BslDocumentationComment(Module module,
 Method method,
 int[] lineLocalOffsets)

Constructor

Parameters:

module - actual Module which contains Method with this documentation comment, cannot be null

method - Method with this documentation comment, cannot be null

lineLocalOffsets - offsets of the each line in comment relatively to the total method text, cannot be null

BslDocumentationComment

public BslDocumentationComment(BslContextDefMethod method)

Constructor by BslContextDefMethod

Parameters:

method - BslContextDefMethod contains content of the documentation comment adn offsets of the each line in comment relatively to the total method text, cannot be null

Method Details

getModule

public Module getModule()

Gets the module Module of the documentation comment

Returns:

the module Module of the documentation comment, can be null if model created not from method documentation comment nodes.

getMethod

public Method getMethod()

Gets the method Method of the documentation comment

Returns:

the method Method can be null if model created not from method documentation comment nodes.

getLineGlobalOffsets

public int[] getLineGlobalOffsets()

Gets the offsets of the each line in comment relatively to the total method text, cannot be null

Returns:

the offsets of the each line in comment, cannot return null.

getParent

public IDescriptionPart getParent()

Description copied from interface: IDescriptionPart

Gets the parent object.

Specified by:

getParent in interface IDescriptionPart

Returns:

the parent object, can return null if it is root object BslDocumentationComment or object created separetly form parsing source code.

getOffset

public int getOffset()

Description copied from interface: IDescriptionPart

Gets offset of the begining part. Offset - local inline offset

Specified by:

getOffset in interface IDescriptionPart

Returns:

offset of the begining part.

getLineNumber

public int getLineNumber()

Description copied from interface: IDescriptionPart

Gets the line nubmer corresponding to part. Numeration starts from 0 Line number - line number corresponding to the begining of the documentation comment. Each comment starts with line with number 0

Specified by:

getLineNumber in interface IDescriptionPart

Returns:

the line nubmer corresponding to part

match

public boolean match(int lineNumber,
 int offset)

Description copied from interface: IDescriptionPart

Checks that this description part corresponding to the concrete line number and offset

Specified by:

match in interface IDescriptionPart

Parameters:

lineNumber - number of the documentation comment line

offset - local offset on the comment line

Returns:

true if this description part corresponding to the send line number and offset, false otherwise

getDescription

public BslDocumentationComment.Description getDescription()

Gets the main comment BslDocumentationComment.Description

Returns:

the main comment BslDocumentationComment.Description, never null

setDescription

public void setDescription(BslDocumentationComment.Description description)

Sets the main comment BslDocumentationComment.Description

Parameters:

description - new comment BslDocumentationComment.Description, cannot be null

setParametersSection

public void setParametersSection(BslDocumentationComment.ParametersSection parametersSection)

Sets new BslDocumentationComment.ParametersSection

Parameters:

parametersSection - new BslDocumentationComment.ParametersSection, can be null if there is no this section

getParametersSection

public BslDocumentationComment.ParametersSection getParametersSection()

Gets the actual description of the BslDocumentationComment.ParametersSection

Returns:

actual description of the BslDocumentationComment.ParametersSection, can be null if there is no it

setReturnSection

public void setReturnSection(BslDocumentationComment.ReturnSection returnSection)

Sets new BslDocumentationComment.ReturnSection

Parameters:

returnSection - BslDocumentationComment.ReturnSection, can be null of there is no this section

getReturnSection

public BslDocumentationComment.ReturnSection getReturnSection()

Gets the actual description of the BslDocumentationComment.ReturnSection

Returns:

actual description of the BslDocumentationComment.ReturnSection, can be null if there is no it

getExampleSection

public BslDocumentationComment.Section getExampleSection()

Gets the actual description of the example BslDocumentationComment.Section

Returns:

actual description of the example BslDocumentationComment.Section, can be null if there is no it

setExampleSection

public void setExampleSection(BslDocumentationComment.Section exampleSection)

Sets new example BslDocumentationComment.Section

Parameters:

exampleSection - example BslDocumentationComment.Section, can be null of there is no this section

getCallOptionsSection

public BslDocumentationComment.Section getCallOptionsSection()

Gets the actual description of the call options BslDocumentationComment.Section

Returns:

actual description of the call options BslDocumentationComment.Section, can be null if there is no it

setCallOptionsSection

public void setCallOptionsSection(BslDocumentationComment.Section callOptionsSection)

Sets new call options BslDocumentationComment.Section

Parameters:

exampleSection - call options BslDocumentationComment.Section, can be null of there is no this section

isDeprecated

public boolean isDeprecated()

Checks that special keyword for marking method as deprecated found

Returns:

true if the main description part start with keywords IBslCommentToken.DEPRECATED or IBslCommentToken.DEPRECATED_RU, false otherwise

setDeprecated

public void setDeprecated(boolean deprecated)

Sets that documentation comment corresponding to the deprecated method

Parameters:

deprecated - true if documentation comment corresponding to the deprecated method, false otherwise

parse

public void parse(List<String> templateLines,
 List<String> paramNames)

Parses comment lines corresponding to the new documentation format

Parameters:

templateLines - initial string line of the comment content, cannot be null

paramNames - names of the FormalParam, cannot be null

parseOldFormat

public void parseOldFormat(List<String> templateLines,
 List<String> paramNames)

Parses comment lines corresponding to the old documentation format

Parameters:

templateLines - initial string line of the comment content, cannot be null

paramNames - names of the FormalParam, cannot be null

computeReturnTypes

public Collection<TypeItem> computeReturnTypes(org.eclipse.xtext.scoping.IScope typeScope,
 org.eclipse.xtext.scoping.IScopeProvider scopeProvider,
 org.eclipse.xtext.naming.IQualifiedNameConverter qualifiedNameConverter,
 BslMultiLineCommentDocumentationProvider commentProvider,
 IV8ProjectManager v8ProjectManager,
 boolean oldFormat,
 org.eclipse.emf.ecore.EObject context,
 BmOperationContext typeComputationContext)

Computes real types for BslDocumentationComment.ReturnSection

Parameters:

typeScope - actual types IScope, cannot be null

scopeProvider - actual IScopeProvider, cannot be null

qualifiedNameConverter - actual IQualifiedNameConverter, cannot be null

commentProvider - actual BslMultiLineCommentDocumentationProvider, cannot be null

v8ProjectManager - IV8ProjectManager for getting IV8Project by EObject, cannot be null

oldFormat - true if comment in old format, false in new format

context - EObject for resolving elements, cannot be null

typeComputationContext - Type system computation context. May not be null

Returns:

collection of TypeItems described in BslDocumentationComment.ReturnSection, never null

computeParameterTypes

public Collection<TypeItem> computeParameterTypes(String name,
 org.eclipse.xtext.scoping.IScope typeScope,
 org.eclipse.xtext.scoping.IScopeProvider scopeProvider,
 org.eclipse.xtext.naming.IQualifiedNameConverter qualifiedNameConverter,
 BslMultiLineCommentDocumentationProvider commentProvider,
 IV8ProjectManager v8ProjectManager,
 boolean oldFormat,
 org.eclipse.emf.ecore.EObject context,
 BmOperationContext typeComputationContext)

Computes real types for parameter from ParameterSection

Parameters:

name - name of the parameter from ParameterSection, cannot be null

typeScope - actual types IScope, cannot be null

scopeProvider - actual IScopeProvider, cannot be null

qualifiedNameConverter - actual IQualifiedNameConverter, cannot be null

commentProvider - actual BslMultiLineCommentDocumentationProvider, cannot be null

v8ProjectManager - IV8ProjectManager for getting IV8Project by EObject, cannot be null

oldFormat - true if comment in old format, false in new format

context - EObject for resolving elements, cannot be null

typeComputationContext - Type system computation context. May not be null

Returns:

collection of TypeItems described in ParameterSection for parameter with concrete name, never null

getCommentSection

public BslDocumentationComment.Section getCommentSection(int lineNumber)

Gets actual documentation comment BslDocumentationComment.Section by line number

Parameters:

lineNumber - number of the comment line for getting BslDocumentationComment.Section

Returns:

BslDocumentationComment.Section corresponding to the line number, can be null if there is no section on this line

getDescriptionPart

public IDescriptionPart getDescriptionPart(int lineNumber,
 int offset)

Gets actual documentation comment IDescriptionPart by line number and local line offset

Parameters:

lineNumber - number of the comment line for getting IDescriptionPart

offset - local line offset for getting IDescriptionPart

Returns:

IDescriptionPart corresponding to the line number and local line offset, can be null if there is no description part on this line number and offset