| Am I using a good approach for creating a documentation formatter [message #1722981] |
Wed, 10 February 2016 16:10  |
|
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 #1723948 is a reply to message #1723591] |
Fri, 19 February 2016 08:23  |
|
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 |
|
|
Powered by
FUDForum. Page generated in 0.04176 seconds
] 
Search
Help
Register
Login
Home
