Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Modeling » TMF (Xtext) » Am I using a good approach for creating a documentation formatter
Am I using a good approach for creating a documentation formatter [message #1722981] Wed, 10 February 2016 16:10 Go to next message
Stéphane Galland is currently offline Stéphane GallandFriend
Messages: 123
Registered: July 2014
Location: Belfort, France
Senior Member
I'm needing to format the documentation for my DSL.

I have creating something working, that I will explain below.

My question is: is a better way exist for doing this?

I did:

  • a MWE2 fragment that generates a "IDocumentationFormatter" and a default implementation.
  • the "class SARLMultilineCommentReplacer extends CommentReplacer" that is calling the formatter for "/* */" comments.
  • the "class SARLSinglelineCommentReplacer extends CommentReplacer" that is calling the formatter for "//" comments.
  • a subclass of "XtendFormatter" and override the function "createCommentReplacer" for creating an instance of one of the two previous classes.

[Updated on: Fri, 19 February 2016 08:49]

Report message to a moderator

Re: Am I use a good approach for creating a documentation formatter [message #1723591 is a reply to message #1722981] Tue, 16 February 2016 16:57 Go to previous messageGo to next message
Moritz Eysholdt is currently offline Moritz EysholdtFriend
Messages: 161
Registered: July 2009
Location: Kiel, Germany
Senior Member
Stephane Galland wrote on Wed, 10 February 2016 17:10

My question is: is a better way exist for doing this?


You'll need to explain what you want to achieve to allow us to answer this question.

The standard way to implement a formatter is to activate the fragment
org.eclipse.xtext.xtext.generator.formatting.Formatter2Fragment2 for your language.

This will generate a class called
/src/com/mycompany/mydsl/MyDSLFormatter.xtend

And that's the class you customize. That class is expected to extend the formatter of your super language. If your language has no super language or extends common.Terminals, your formatter impl should extend
org.eclipse.xtext.formatting2.AbstractFormatter2
Re: Am I use a good approach for creating a documentation formatter [message #1723948 is a reply to message #1723591] Fri, 19 February 2016 08:23 Go to previous message
Stéphane Galland is currently offline Stéphane GallandFriend
Messages: 123
Registered: July 2014
Location: Belfort, France
Senior Member
Dear Moritz.

Thank you for your reply.
I have already activated the fragment, and created a formater for the source code of my DSL. It's working as expected.

Now, I'm facing the problem of the documentation formatting. I want to output the comment's text with a specific layout.

For doing that I have explored the code of the Xtext API, and do the things below. It's seems to work; but because I do this from scratch without tutorial nor example, I would like to determine if there is some other recommended way for creating a formater of the comment/documentation that is different of mine.

1) I wrote a MWE2 fragment that is generating the interface IDocumentationFormatter and the implementation SarlDocumentationFormatter (this implementation formats the comments' text by adding the "*" character at the beginning of each comment line):
public interface IDocumentationFormatter {
	String getMultilineCommentLinePrefix();
	String getMultilineCommentStartSymbols();
	String getMultilineCommentEndSymbols();
	String getSinglelineCommentPrefix();
	String formatMultilineComment(String doc);
	String formatMultilineComment(String doc, String indentation);
	void formatMultilineComment(String doc, IAppendable appendable);
	void formatMultilineComment(String doc, String indentation, IAppendable appendable);
	void formatMultilineComment(ITextReplacerContext context, IComment comment);
	String formatSinglelineComment(String doc);
	String formatSinglelineComment(String doc, String indentation);
	void formatSinglelineComment(String doc, IAppendable appendable);
	void formatSinglelineComment(String doc, String indentation, IAppendable appendable);
	void formatSinglelineComment(ITextReplacerContext context, IComment comment);
}


2) I wrote the classes SARLMultilineCommentReplacer and SARLSinglelineCommentReplacer for using my formater. Below the SARLMultilineCommentReplacer class. The BugMultilineCommentIndentation class is fixing a known bug related to the invalid indentation of comments at the beginning of blocks.
public class SARLMultilineCommentReplacer extends CommentReplacer {
	@Inject
	private IDocumentationFormatter formatter;
	@Inject
	private BugMultilineCommentIndentation bugfix;
	public SARLMultilineCommentReplacer(IComment comment) {
		super(comment);
	}
	public void configureWhitespace(WhitespaceReplacer leading, WhitespaceReplacer trailing) {
		if (leading.getRegion().getOffset() > 0) {
			IHiddenRegionFormatting formatting = leading.getFormatting();
			formatting.setNewLinesDefault(1);
			formatting.setNewLinesMin(1);
			formatting.setNewLinesMax(1);
			formatting.setNoIndentation(false);
		}
		if (trailing.getRegion().getOffset() > 0) {
			IHiddenRegionFormatting formatting = trailing.getFormatting();
			formatting.setNewLinesDefault(1);
			formatting.setNewLinesMin(1);
			formatting.setNewLinesMax(1);
			formatting.setNoIndentation(false);
		}
	}
	public ITextReplacerContext createReplacements(ITextReplacerContext context) {
		IComment comment = getComment();
		if (context != null && comment != null) {
			this.formatter.formatMultilineComment(this.bugfix.fix(context, comment), comment);
		}
		return context;
	}
}


3) I subclassed XtendFormatter for creating my implementations of the Replacers.
public class SARLFormatter extends XtendFormatter {
    ...
   @Injector
   private Injector injector;
   public ITextReplacer createCommentReplacer(IComment comment) {
		EObject grammarElement = comment.getGrammarElement();
		if (grammarElement instanceof AbstractRule) {
			String ruleName = ((AbstractRule) grammarElement).getName();
			CommentReplacer replacer = null;
			if (ruleName.startsWith("ML")) {
				replacer = new SARLMultilineCommentReplacer(comment);
			} else if (ruleName.startsWith("SL")) {
				replacer = new SARLSinglelineCommentReplacer(comment);
			}
			if (replacer != null) {
				this.injector.injectMembers(replacer);
				return replacer;
			}
		}
		String elementName = new GrammarElementTitleSwitch().showQualified().showRule().doSwitch(grammarElement);
		throw new IllegalStateException(
				MessageFormat.format(Messages.SARLFormatter_0,
						ITextReplacer.class.getSimpleName(), elementName));
	}
    ...
}

[Updated on: Fri, 19 February 2016 08:48]

Report message to a moderator

Previous Topic:Cross-references with alias
Next Topic:Export XMI
Goto Forum:
  


Current Time: Sat Sep 18 08:56:52 GMT 2021

Powered by FUDForum. Page generated in 0.01416 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top