sigmasternchen/xtext-core
1
0
Fork 0
mirror of https://github.com/sigmasternchen/xtext-core synced 2025-03-16 08:48:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[textRegionAccess] improved documentation and parameter naming

Browse source 
Signed-off-by: Moritz Eysholdt <moritz.eysholdt@typefox.io>
This commit is contained in:
Moritz Eysholdt 2016-04-19 13:58:18 +02:00
parent 62354a7ebf
commit 8fd3b45a4a
2 changed files with 33 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
plugins/org.eclipse.xtext/src/org/eclipse/xtext/formatting2/regionaccess/ITextRegionAccess.java
View file

@ -13,8 +13,8 @@ import org.eclipse.xtext.resource.XtextResource;
/**
* <p>
* This class provides access to {@link ITextSegment text regions } based on the semantic model. A text region describes
* the offset and length in characters of a semantic elements within a text document.
* This class provides access to {@link ITextSegment text regions } based on the semantic model. A text region describes the offset and
* length in characters of a semantic elements within a text document.
* </p>
*
* <p>
@ -22,15 +22,14 @@ import org.eclipse.xtext.resource.XtextResource;
* </p>
*
* <p>
* The text regions are arranged as a linked list of strictly alternating {@link ISemanticRegion semantic regions} and
* {@link IHiddenRegion hidden region}. HiddenRegions group all hidden tokens (typically whitespace, newlines, tabs and
* comments) between two semantic tokens. HiddenRegions are empty, but do exist, if there are no hidden tokens between
* two semantic elements.
* The text regions are arranged as a linked list of strictly alternating {@link ISemanticRegion semantic regions} and {@link IHiddenRegion
* hidden region}. HiddenRegions group all hidden tokens (typically whitespace, newlines, tabs and comments) between two semantic tokens.
* HiddenRegions are empty, but do exist, if there are no hidden tokens between two semantic elements.
* </p>
*
* <p>
* Tokens are considered to be hidden, when they have been parsed via terminal rule referenced in "hidden(...)" in the
* Xtext grammar. In the node model, hidden tokens are usually marked as {@link ILeafNode#isHidden() hidden == true}.
* Tokens are considered to be hidden, when they have been parsed via terminal rule referenced in "hidden(...)" in the Xtext grammar. In the
* node model, hidden tokens are usually marked as {@link ILeafNode#isHidden() hidden == true}.
* </p>
*
* <p>
@ -38,8 +37,8 @@ import org.eclipse.xtext.resource.XtextResource;
* </p>
*
* <p>
* A {@link IHiddenRegion} contains a list of {@link IHiddenRegionPart parts}, which are either {@link IWhitespace white
* space} or {@link IComment comments}. A HiddenRegion can be empty.
* A {@link IHiddenRegion} contains a list of {@link IHiddenRegionPart parts}, which are either {@link IWhitespace white space} or
* {@link IComment comments}. A HiddenRegion can be empty.
* </p>
*
* The purpose of this class is:
@ -71,7 +70,10 @@ public interface ITextRegionAccess {
ILineRegion regionForLineAtOffset(int offset);
IEObjectRegion regionForEObject(EObject object);
/**
* Returns a the text region for a semantic element (i.e. and EObject from the AST).
*/
IEObjectRegion regionForEObject(EObject semanticElement);
ITextSegment regionForDocument();

37
plugins/org.eclipse.xtext/src/org/eclipse/xtext/formatting2/regionaccess/ITextRegionExtensions.java
View file

@ -13,55 +13,58 @@ import org.eclipse.xtext.ParserRule;
import org.eclipse.xtext.RuleCall;
/**
* This class is a facade on top of an {@link ITextRegionAccess}.
*
* It provides convenience methods to be used by formatters that are implemented in the Xtend programming language.
*
* @author Moritz Eysholdt - Initial contribution and API
*/
public interface ITextRegionExtensions {
ISemanticRegionsFinder allRegionsFor(EObject object);
ISemanticRegionsFinder allRegionsFor(EObject semanticElement);
Iterable<ISemanticRegion> allSemanticRegions(EObject object);
Iterable<ISemanticRegion> allSemanticRegions(EObject semanticElement);
ITextRegionAccess getTextRegionAccess();
/**
* @return the {@link RuleCall} or the assigned {@link Action} that led to the construction of this EObject. For the
* model's root element, the {@link ParserRule} is returned.
* @return the {@link RuleCall} or the assigned {@link Action} that led to the construction of this EObject. For the model's root
* element, the {@link ParserRule} is returned.
*/
EObject grammarElement(EObject obj);
EObject grammarElement(EObject semanticElement);
ISemanticRegionFinder immediatelyFollowing(EObject owner);
ISemanticRegionFinder immediatelyFollowing(EObject semanticElement);
ISemanticRegionFinder immediatelyPreceding(EObject owner);
ISemanticRegionFinder immediatelyPreceding(EObject semanticElement);
/**
* @return true, if the EObject's text range contains a line-wrap ("\n"). The EObject's text range reaches from the
* beginning of its first semantic region to the end of its last semantic region.
* @return true, if the EObject's text range contains a line-wrap ("\n"). The EObject's text range reaches from the beginning of its
* first semantic region to the end of its last semantic region.
*/
boolean isMultiline(EObject object);
boolean isMultiline(EObject semanticElement);
/**
* @return the {@link IHiddenRegion} that follows after the EObject's last {@link ISemanticRegion}.
*
* @see #previousHiddenRegion(EObject)
*/
IHiddenRegion nextHiddenRegion(EObject owner);
IHiddenRegion nextHiddenRegion(EObject semanticElement);
/**
* @return the {@link IHiddenRegion} that precedes the EObject's first {@link ISemanticRegion}.
*
* @see #nextHiddenRegion(EObject)
*/
IHiddenRegion previousHiddenRegion(EObject owner);
IHiddenRegion previousHiddenRegion(EObject semanticElement);
ISemanticRegionsFinder regionFor(EObject object);
ISemanticRegionsFinder regionFor(EObject semanticElement);
/**
* @return a text region that reaches from the beginning of its first semantic region to the end of its last
* semantic region.
* @return a text region that reaches from the beginning of its first semantic region to the end of its last semantic region.
*/
IEObjectRegion regionForEObject(EObject object);
IEObjectRegion regionForEObject(EObject semanticElement);
Iterable<ISemanticRegion> semanticRegions(EObject object);
Iterable<ISemanticRegion> semanticRegions(EObject semanticElement);
}