[#241] Merge branch 'markdown' into 'master'

compiler/core/antlr/ZserioLexer.g4

@@ -102,6 +102,7 @@ WS : [\r\n\f\t ] -> skip ;
 
 // comments
 DOC_COMMENT : '/**' .*? '*/' -> channel(DOC) ;
+MARKDOWN_COMMENT : '/*!' .*? '!'?'*/' -> channel(DOC) ;
 BLOCK_COMMENT : '/*' .*? '*/' -> channel(HIDDEN) ;
 LINE_COMMENT : '//' ~[\r\n\f]* -> channel(HIDDEN) ;
 
@@ -113,7 +114,7 @@ fragment STRING_CHARACTER
     |   '\\' ["\\rnft]
     |   '\\u' HEX_DIGIT HEX_DIGIT HEX_DIGIT HEX_DIGIT
     |   '\\x' HEX_DIGIT HEX_DIGIT
-    |   '\\0' [0-3]? OCTAL_DIGIT OCTAL_DIGIT? 
+    |   '\\0' [0-3]? OCTAL_DIGIT OCTAL_DIGIT?
     ;
 STRING_LITERAL : '"' STRING_CHARACTER* '"' ;
 

compiler/core/src/zserio/ast/Constant.java

@@ -1,11 +1,9 @@
 package zserio.ast;
 
-import zserio.tools.HashUtil;
-
 /**
  * AST node for Constants.
  */
-public class Constant extends DocumentableAstNode implements Comparable<Constant>
+public class Constant extends DocumentableAstNode
 {
     /**
      * Constructor.
@@ -43,29 +41,6 @@ public void visitChildren(ZserioAstVisitor visitor)
         valueExpression.accept(visitor);
     }
 
-    @Override
-    public int compareTo(Constant other)
-    {
-        return getName().compareTo(other.getName());
-    }
-
-    @Override
-    public boolean equals(Object other)
-    {
-        if ( !(other instanceof Constant) )
-            return false;
-
-        return (this == other) || compareTo((Constant)other) == 0;
-    }
-
-    @Override
-    public int hashCode()
-    {
-        int hash = HashUtil.HASH_SEED;
-        hash = HashUtil.hash(hash, getName());
-        return hash;
-    }
-
     /**
      * Gets the package in which this constant is defined.
      *

compiler/core/src/zserio/ast/DocComment.java

@@ -1,48 +1,17 @@
 package zserio.ast;
 
-import java.util.Collections;
-import java.util.List;
-
 /**
- * Class representing a single documentation comment.
+ * Base class representing a single documentation comment.
  */
-public class DocComment extends AstNodeBase
+public abstract class DocComment extends AstNodeBase
 {
     /**
      * Constructor.
      *
      * @param location     AST node location.
-     * @param paragraphs   Doc comment paragraphs.
      */
-    public DocComment(AstLocation location, List<DocParagraph> paragraphs)
+    public DocComment(AstLocation location)
     {
         super(location);
-
-        this.paragraphs = paragraphs;
-    }
-
-    @Override
-    public void accept(ZserioAstVisitor visitor)
-    {
-        visitor.visitDocComment(this);
-    }
-
-    @Override
-    public void visitChildren(ZserioAstVisitor visitor)
-    {
-        for (DocParagraph paragraph : paragraphs)
-            paragraph.accept(visitor);
     }
-
-    /**
-     * Gets doc comment paragraphs.
-     *
-     * @return List of paragraphs.
-     */
-    public List<DocParagraph> getParagraphs()
-    {
-        return Collections.unmodifiableList(paragraphs);
-    }
-
-    private final List<DocParagraph> paragraphs;
 }

compiler/core/src/zserio/ast/DocCommentAstBuilder.java

@@ -23,7 +23,7 @@ public Object visitDocComment(DocCommentParser.DocCommentContext ctx)
     {
         visitChildren(ctx);
 
-        return new DocComment(new AstLocation(docCommentToken), paragraphs);
+        return new DocCommentClassic(new AstLocation(docCommentToken), paragraphs);
     }
 
     @Override

compiler/core/src/zserio/ast/DocCommentClassic.java

@@ -0,0 +1,48 @@
+package zserio.ast;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Class representing a single documentation comment in classic style.
+ */
+public class DocCommentClassic extends DocComment
+{
+    /**
+     * Constructor.
+     *
+     * @param location     AST node location.
+     * @param paragraphs   Doc comment paragraphs.
+     */
+    public DocCommentClassic(AstLocation location, List<DocParagraph> paragraphs)
+    {
+        super(location);
+
+        this.paragraphs = paragraphs;
+    }
+
+    @Override
+    public void accept(ZserioAstVisitor visitor)
+    {
+        visitor.visitDocCommentClassic(this);
+    }
+
+    @Override
+    public void visitChildren(ZserioAstVisitor visitor)
+    {
+        for (DocParagraph paragraph : paragraphs)
+            paragraph.accept(visitor);
+    }
+
+    /**
+     * Gets doc comment paragraphs.
+     *
+     * @return List of paragraphs.
+     */
+    public List<DocParagraph> getParagraphs()
+    {
+        return Collections.unmodifiableList(paragraphs);
+    }
+
+    private final List<DocParagraph> paragraphs;
+}

compiler/core/src/zserio/ast/DocCommentManager.java

@@ -146,6 +146,22 @@ private Token findDocTokenBefore(Token token)
     }
 
     private DocComment parseDocComment(Token docCommentToken)
+    {
+        if (docCommentToken.getType() == ZserioLexer.MARKDOWN_COMMENT)
+            return parseDocCommentMarkdown(docCommentToken);
+        else
+            return parseDocCommentClassic(docCommentToken);
+    }
+
+    private DocCommentMarkdown parseDocCommentMarkdown(Token docCommentToken)
+    {
+        final String markdown = docCommentToken.getText()
+                .replaceAll("^/\\*!\\s*", "") // strip from beginning
+                .replaceAll("\\s*!?\\*/$", ""); // strip from the end
+        return new DocCommentMarkdown(new AstLocation(docCommentToken), markdown);
+    }
+
+    private DocCommentClassic parseDocCommentClassic(Token docCommentToken)
     {
         try
         {
@@ -173,7 +189,7 @@ private DocComment parseDocComment(Token docCommentToken)
             }
 
             final DocCommentAstBuilder docCommentAstBuilder = new DocCommentAstBuilder(docCommentToken);
-            final DocComment docComment = (DocComment)docCommentAstBuilder.visit(tree);
+            final DocCommentClassic docComment = (DocCommentClassic)docCommentAstBuilder.visit(tree);
 
             return docComment;
         }

compiler/core/src/zserio/ast/DocCommentMarkdown.java

@@ -0,0 +1,43 @@
+package zserio.ast;
+
+/**
+ * Class representing a single documentation comment in markdown style.
+ */
+public class DocCommentMarkdown extends DocComment
+{
+    /**
+     * Constructor.
+     *
+     * @param location AST node location.
+     * @param markdown Markdown documentation.
+     */
+    public DocCommentMarkdown(AstLocation location, String markdown)
+    {
+        super(location);
+
+        this.markdown = markdown;
+    }
+
+    @Override
+    public void accept(ZserioAstVisitor visitor)
+    {
+        visitor.visitDocCommentMarkdown(this);
+    }
+
+    @Override
+    public void visitChildren(ZserioAstVisitor visitor)
+    {
+    }
+
+    /**
+     * Gets markdown documentation.
+     *
+     * @return Markdown documentation.
+     */
+    public String getMarkdown()
+    {
+        return markdown;
+    }
+
+    final String markdown;
+}

compiler/core/src/zserio/ast/DocumentableAstNode.java

@@ -22,7 +22,7 @@ public DocumentableAstNode(AstLocation location, DocComment docComment)
     public void visitChildren(ZserioAstVisitor visitor)
     {
         if (docComment != null)
-            visitor.visitDocComment(docComment);
+            docComment.accept(visitor);
     }
 
     /**

compiler/core/src/zserio/ast/ZserioAstDefaultVisitor.java

@@ -170,7 +170,11 @@ public void visitInstantiateType(InstantiateType templateInstantiation)
     }
 
     @Override
-    public void visitDocComment(DocComment docComment)
+    public void visitDocCommentClassic(DocCommentClassic docComment)
+    {}
+
+    @Override
+    public void visitDocCommentMarkdown(DocCommentMarkdown docComment)
     {}
 
     @Override

compiler/core/src/zserio/ast/ZserioAstVisitor.java

@@ -286,11 +286,18 @@ public interface ZserioAstVisitor
     void visitInstantiateType(InstantiateType templateInstantiation);
 
     /**
-     * Visits a documentation comment.
+     * Visits a classic-style documentation comment.
      *
-     * @param docComment Documentation comment AST node.
+     * @param docComment Classic-style documentation comment AST node.
      */
-    void visitDocComment(DocComment docComment);
+    void visitDocCommentClassic(DocCommentClassic docComment);
+
+    /**
+     * Visits a markdown-style documentation comment.
+     *
+     * @param docComment Markdown-style documentation comment AST node.
+     */
+    void visitDocCommentMarkdown(DocCommentMarkdown docComment);
 
     /**
      * Visits documentation paragraph.

compiler/core/src/zserio/ast/ZserioAstWalker.java

@@ -249,7 +249,13 @@ public void visitInstantiateType(InstantiateType templateInstantiation)
     }
 
     @Override
-    public void visitDocComment(DocComment docComment)
+    public void visitDocCommentClassic(DocCommentClassic docComment)
+    {
+        docComment.visitChildren(this);
+    }
+
+    @Override
+    public void visitDocCommentMarkdown(DocCommentMarkdown docComment)
     {
         docComment.visitChildren(this);
     }

compiler/core/src/zserio/emit/common/FileUtil.java

@@ -1,6 +1,8 @@
 package zserio.emit.common;
 
 import java.io.File;
+import java.io.IOException;
+import java.io.PrintWriter;
 
 /**
  * File utilities for Zserio emitters.
@@ -29,4 +31,25 @@ public static void createOutputDirectory(File outputFile) throws ZserioEmitExcep
                 throw new ZserioEmitException("Can't create output directory: " + parentDir.toString());
         }
     }
+
+    /**
+     * Creates writer for given file.
+     *
+     * @param outputFile Output file for which to create writer.
+     *
+     * @return Created writer.
+     *
+     * @throws ZserioEmitException Throws if writer cannot be created.
+     */
+    public static PrintWriter createWriter(File outputFile) throws ZserioEmitException
+    {
+        try
+        {
+            return new PrintWriter(outputFile, "UTF-8");
+        }
+        catch (IOException exception)
+        {
+            throw new ZserioEmitException(exception.getMessage());
+        }
+    }
 }