GNOME.org
 

[gtksourceview] jsdoc.lang: Add language definition

commit b26f685497d528962ddc45f742512bbd59129589
Author: Jeffery To <jeffery to gmail com>
Date:   Thu Nov 14 03:11:36 2019 +0800

    jsdoc.lang: Add language definition
    
    This adds basic highlighting for JSDoc, a markup language for
    documenting JavaScript source code.
    
    Fixes #90.

 data/language-specs/javascript.lang |  49 ++++++-
 data/language-specs/jsdoc.lang      | 264 ++++++++++++++++++++++++++++++++++++
 po/POTFILES.skip                    |   1 +
 tests/syntax-highlighting/file.html |   5 +
 tests/syntax-highlighting/file.j    |  77 +++++++++++
 tests/syntax-highlighting/file.js   |  77 +++++++++++
 tests/syntax-highlighting/file.jsx  |  77 +++++++++++
 tests/syntax-highlighting/file.ts   |  77 +++++++++++
 tests/syntax-highlighting/file.tsx  |  77 +++++++++++
 9 files changed, 698 insertions(+), 6 deletions(-)
---
diff --git a/data/language-specs/javascript.lang b/data/language-specs/javascript.lang
index 701c70be..0ba66d83 100644
--- a/data/language-specs/javascript.lang
+++ b/data/language-specs/javascript.lang
@@ -36,6 +36,8 @@
   <styles>
 
     <!-- General -->
+    <style id="comment"               name="Comment"                map-to="def:comment"/>
+    <style id="doc-comment"           name="Documentation comment"  map-to="def:doc-comment"/>
     <style id="error"                 name="Error"                  map-to="def:error"/>
     <style id="keyword"               name="Keyword"                map-to="def:keyword"/>
     <style id="reserved-word"         name="Reserved word"          map-to="def:reserved"/>
@@ -294,21 +296,21 @@
     <!-- includes def:in-comment instead of def:in-line-comment,
          because line continuations are not allowed inside single-line
          comments -->
-    <context id="_c-like-comment" style-ref="def:comment" end-at-line-end="true" 
class-disabled="no-spell-check" class="comment">
+    <context id="_c-like-comment" style-ref="comment" end-at-line-end="true" class-disabled="no-spell-check" 
class="comment">
       <start>//</start>
       <include>
         <context ref="def:in-comment"/>
       </include>
     </context> <!-- /_c-like-comment -->
 
-    <context id="_c-like-comment-no-extend-parent" style-ref="def:comment" end-at-line-end="true" 
class-disabled="no-spell-check" class="comment" extend-parent="false">
+    <context id="_c-like-comment-no-extend-parent" style-ref="comment" end-at-line-end="true" 
class-disabled="no-spell-check" class="comment" extend-parent="false">
       <start>//</start>
       <include>
         <context ref="def:in-comment"/>
       </include>
     </context> <!-- /_c-like-comment-no-extend-parent -->
 
-    <context id="_c-like-comment-multiline-no-extend-parent" style-ref="def:comment" 
class-disabled="no-spell-check" class="comment" extend-parent="false">
+    <context id="_c-like-comment-multiline-no-extend-parent" style-ref="comment" 
class-disabled="no-spell-check" class="comment" extend-parent="false">
       <start>/\*</start>
       <end>\*/</end>
       <include>
@@ -316,11 +318,45 @@
       </include>
     </context> <!-- /_c-like-comment-multiline-no-extend-parent -->
 
+    <context id="jsdoc-embedded-lang-hooks">
+      <include>
+        <context ref="embedded-lang-hooks"/>
+
+        <context end-parent="true">
+          <start>(?=\*/)</start>
+          <end>\%{def:always-match}</end>
+        </context>
+
+        <context ref="jsdoc:embedded-lang-hooks" original="true"/>
+      </include>
+    </context>
+
+    <replace id="jsdoc:embedded-lang-hooks" ref="jsdoc-embedded-lang-hooks"/>
+
+    <context id="doc-comment" style-ref="doc-comment" class-disabled="no-spell-check" class="comment">
+      <start>/\*\*(?![\*/])</start>
+      <end>\*/</end>
+      <include>
+        <context ref="def:in-comment"/>
+        <context ref="jsdoc:jsdoc"/>
+      </include>
+    </context> <!-- /doc-comment -->
+
+    <context id="doc-comment-no-extend-parent" style-ref="doc-comment" class-disabled="no-spell-check" 
class="comment" extend-parent="false">
+      <start>/\*\*(?![\*/])</start>
+      <end>\*/</end>
+      <include>
+        <context ref="def:in-comment"/>
+        <context ref="jsdoc:jsdoc"/>
+      </include>
+    </context> <!-- /doc-comment-no-extend-parent -->
+
     <context id="comments">
       <include>
         <context ref="_c-like-comment"/>
-        <context ref="def:c-like-comment-multiline"/>
-        <context ref="def:c-like-close-comment-outside-comment"/>
+        <context ref="doc-comment"/>
+        <context ref="def:c-like-comment-multiline" style-ref="comment"/>
+        <context ref="def:c-like-close-comment-outside-comment" style-ref="error"/>
       </include>
     </context> <!-- /comments -->
 
@@ -328,8 +364,9 @@
     <context id="comments-no-extend-parent">
       <include>
         <context ref="_c-like-comment-no-extend-parent"/>
+        <context ref="doc-comment-no-extend-parent"/>
         <context ref="_c-like-comment-multiline-no-extend-parent"/>
-        <context ref="def:c-like-close-comment-outside-comment"/>
+        <context ref="def:c-like-close-comment-outside-comment" style-ref="error"/>
       </include>
     </context> <!-- /comments-no-extend-parent -->
 
diff --git a/data/language-specs/jsdoc.lang b/data/language-specs/jsdoc.lang
new file mode 100644
index 00000000..c55633e9
--- /dev/null
+++ b/data/language-specs/jsdoc.lang
@@ -0,0 +1,264 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+ This file is part of GtkSourceView
+
+ Author: Jeffery To <jeffery to gmail com>
+ Copyright (C) 2019 Jeffery To <jeffery to gmail com>
+
+ GtkSourceView is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ GtkSourceView is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License
+ along with this library; if not, see <http://www.gnu.org/licenses/>.
+
+-->
+<language id="jsdoc" name="JSDoc" version="2.0" _section="Markup" hidden="true">
+
+  <styles>
+    <style id="inline-tag"  name="Inline tag" map-to="def:doc-comment-element"/>
+    <style id="type"        name="Type"       map-to="def:doc-comment-element"/>
+    <style id="block-tag"   name="Block tag"  map-to="def:doc-comment-element"/>
+    <style id="note"        name="Note"       map-to="def:note"/>
+    <style id="argument"    name="Argument"   map-to="def:doc-comment-element"/>
+    <style id="event"       name="Event"      map-to="jsdoc:argument"/>
+    <style id="keyword"     name="Keyword"    map-to="jsdoc:argument"/>
+    <style id="namepath"    name="Namepath"   map-to="jsdoc:argument"/>
+    <style id="escape"      name="Escape"/>
+  </styles>
+
+  <keyword-char-class>[a-zA-Z0-9_$]</keyword-char-class>
+
+  <definitions>
+
+    <!--
+         Based on:
+         * JSDoc 3
+           https://jsdoc.app/
+         * Google Closure Compiler
+           https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler
+         * TSDoc
+           https://github.com/microsoft/tsdoc
+           https://api-extractor.com/pages/tsdoc/doc_comment_syntax/
+    -->
+
+    <context id="embedded-lang-hooks"/>
+
+    <context id="escape" style-ref="escape">
+      <match>\\[@{}]</match>
+    </context>
+
+    <context id="inline-tag" style-ref="inline-tag" end-at-line-end="true">
+      <start>\{@</start>
+      <end>\}</end>
+      <include>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="escape"/>
+        <context ref="def:in-comment"/>
+      </include>
+    </context>
+
+    <context id="type" style-ref="type" end-at-line-end="true">
+      <start>\{</start>
+      <end>\}</end>
+      <include>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="escape"/>
+        <context ref="def:in-comment"/>
+      </include>
+    </context>
+
+
+    <!-- Block tags -->
+
+    <define-regex id="argument">[^\s@{*][^\s*]*</define-regex>
+
+    <context id="argument" style-ref="argument" end-parent="true">
+      <start>\%{argument}</start>
+      <end>\%{def:always-match}</end>
+    </context>
+
+    <context id="argument-block-tag" end-at-line-end="true">
+      <start extended="true">
+        @
+        (?:
+          default |
+          tutorial |
+          variation
+        )
+        \%]
+      </start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="argument"/>
+      </include>
+    </context>
+
+    <context id="event-block-tag" end-at-line-end="true">
+      <start extended="true">
+        @
+        (?:
+          emits |
+          event |
+          fires |
+          listens
+        )
+        \%]
+      </start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="argument" style-ref="event"/>
+      </include>
+    </context>
+
+    <context id="keyword-block-tag" end-at-line-end="true">
+      <start extended="true">
+        @
+        (?:
+          access |
+          kind
+        )
+        \%]
+      </start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="argument" style-ref="keyword"/>
+      </include>
+    </context>
+
+    <context id="namepath-block-tag" end-at-line-end="true">
+      <start extended="true">
+        @
+        (?:
+          memberof! |
+          (?:
+            alias |
+            augments |
+            callback |
+            constructs |
+            exports |
+            extends |
+            external |
+            function |
+            func |
+            host |
+            interface |
+            lends |
+            memberof |
+            method |
+            mixes |
+            mixin |
+            name |
+            requires |
+            template |   # closure compiler
+            typeParam |  # tsdoc
+            this
+          )
+          \%]
+        )
+      </start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="argument" style-ref="namepath"/>
+      </include>
+    </context>
+
+    <context id="type-namepath-block-tag" end-at-line-end="true">
+      <start extended="true">
+        @
+        (?:
+          argument |
+          arg |
+          class |
+          constant |
+          constructor |
+          const |
+          member |
+          module |
+          namespace |
+          param |
+          property |
+          prop |
+          typedef |
+          var
+        )
+        \%]
+      </start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+        <context ref="type"/>
+        <context ref="argument" style-ref="namepath"/>
+      </include>
+    </context>
+
+    <context id="borrows-block-tag" end-at-line-end="true">
+      <start>@borrows\%]</start>
+      <end>(?=\S)</end>
+      <include>
+        <context sub-pattern="0" where="start" style-ref="block-tag"/>
+        <context ref="embedded-lang-hooks"/>
+
+        <context style-ref="namepath" once-only="true">
+          <match>\%{argument}</match>
+        </context>
+
+        <context end-parent="true">
+          <start>\%[as\%]</start>
+          <end>(?=\S)</end>
+          <include>
+            <context ref="argument" style-ref="namepath"/>
+          </include>
+        </context>
+
+      </include>
+    </context>
+
+    <context id="note-block-tag" style-ref="block-tag">
+      <match>@todo\%]</match>
+      <include>
+        <context sub-pattern="0" style-ref="note"/>
+      </include>
+    </context>
+
+    <context id="block-tag" style-ref="block-tag">
+      <match>@\%{js:identifier}</match>
+    </context>
+
+
+    <!-- Main context -->
+
+    <context id="jsdoc">
+      <include>
+        <context ref="escape"/>
+        <context ref="inline-tag"/>
+        <context ref="type"/>
+        <context ref="argument-block-tag"/>
+        <context ref="event-block-tag"/>
+        <context ref="keyword-block-tag"/>
+        <context ref="namepath-block-tag"/>
+        <context ref="type-namepath-block-tag"/>
+        <context ref="borrows-block-tag"/>
+        <context ref="note-block-tag"/>
+        <context ref="block-tag"/>
+      </include>
+    </context>
+
+  </definitions>
+</language>
diff --git a/po/POTFILES.skip b/po/POTFILES.skip
index ac7cde60..98e31f3f 100644
--- a/po/POTFILES.skip
+++ b/po/POTFILES.skip
@@ -76,6 +76,7 @@ data/language-specs/javascript-modules.lang
 data/language-specs/javascript-statements.lang
 data/language-specs/javascript-values.lang
 data/language-specs/j.lang
+data/language-specs/jsdoc.lang
 data/language-specs/json.lang
 data/language-specs/jsx.lang
 data/language-specs/julia.lang
diff --git a/tests/syntax-highlighting/file.html b/tests/syntax-highlighting/file.html
index e4c1fcbd..0183fbb1 100644
--- a/tests/syntax-highlighting/file.html
+++ b/tests/syntax-highlighting/file.html
@@ -19,6 +19,11 @@
     <script>a = 'single-quoted string</script>
     <script>a = /regular expression</script>
     <script>a = `template literal</script>
+    <script>/*</script>
+    <script>/**</script>
+    <script>/** {number </script>
+    <script>/** {@link </script>
+    <script>/** @param {string} </script>
   </head>
   <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF"
         vlink="#800080" alink="#FF0000">
diff --git a/tests/syntax-highlighting/file.j b/tests/syntax-highlighting/file.j
index 65ed611e..8e6ee41d 100644
--- a/tests/syntax-highlighting/file.j
+++ b/tests/syntax-highlighting/file.j
@@ -1115,3 +1115,80 @@ with (Math) {
     x = r * cos(PI);
     y = r * sin(PI / 2);
 }
+
+
+/*
+ * JSDoc
+ */
+
+/* Inline tag */
+
+/** {@link String} */
+/**
+ * {@link http://example.com | Ex\{am\}ple}
+ */
+/** {@link*/
+
+
+/* Type */
+
+/** {String} */
+/**
+ * {Foo.B\{a\}r}
+ */
+/** {number*/
+
+
+/* Block tag */
+
+// No arguments
+/** @constructor */
+/**
+ * @deprecated since 1.1.0
+ */
+/** @public*/
+
+// Generic argument
+/** @default 3.14159 */
+/**
+ * @tutorial tutorial-1
+ */
+/** @variation 2*/
+
+// Event name argument
+/** @fires earthquakeEvent */
+/**
+ * @listens touchstart
+ */
+/** @event newEvent*/
+
+// Keyword argument
+/** @access protected */
+/**
+ * @kind module
+ */
+/** @access private*/
+
+// Name/namepath argument
+/** @alias foo */
+/**
+ * @extends bar
+ */
+/** @typeParam T*/
+
+// Type and name arguments
+/** @param {String} name - A \{chosen\} \@name */
+/**
+ * @member {Object} child
+ */
+/** @property {number} num*/
+
+// Borrows block tag
+/** @borrows foo as bar */
+/**
+ * @borrows foo as
+ */
+/** @borrows foo*/
+
+// Todo block tag
+/** @todo write more/less test cases */
diff --git a/tests/syntax-highlighting/file.js b/tests/syntax-highlighting/file.js
index 2e023514..134fd303 100644
--- a/tests/syntax-highlighting/file.js
+++ b/tests/syntax-highlighting/file.js
@@ -814,3 +814,80 @@ with (Math) {
     x = r * cos(PI);
     y = r * sin(PI / 2);
 }
+
+
+/*
+ * JSDoc
+ */
+
+/* Inline tag */
+
+/** {@link String} */
+/**
+ * {@link http://example.com | Ex\{am\}ple}
+ */
+/** {@link*/
+
+
+/* Type */
+
+/** {String} */
+/**
+ * {Foo.B\{a\}r}
+ */
+/** {number*/
+
+
+/* Block tag */
+
+// No arguments
+/** @constructor */
+/**
+ * @deprecated since 1.1.0
+ */
+/** @public*/
+
+// Generic argument
+/** @default 3.14159 */
+/**
+ * @tutorial tutorial-1
+ */
+/** @variation 2*/
+
+// Event name argument
+/** @fires earthquakeEvent */
+/**
+ * @listens touchstart
+ */
+/** @event newEvent*/
+
+// Keyword argument
+/** @access protected */
+/**
+ * @kind module
+ */
+/** @access private*/
+
+// Name/namepath argument
+/** @alias foo */
+/**
+ * @extends bar
+ */
+/** @typeParam T*/
+
+// Type and name arguments
+/** @param {String} name - A \{chosen\} \@name */
+/**
+ * @member {Object} child
+ */
+/** @property {number} num*/
+
+// Borrows block tag
+/** @borrows foo as bar */
+/**
+ * @borrows foo as
+ */
+/** @borrows foo*/
+
+// Todo block tag
+/** @todo write more/less test cases */
diff --git a/tests/syntax-highlighting/file.jsx b/tests/syntax-highlighting/file.jsx
index 941c41f5..39c8a389 100644
--- a/tests/syntax-highlighting/file.jsx
+++ b/tests/syntax-highlighting/file.jsx
@@ -867,3 +867,80 @@ with (Math) {
     x = r * cos(PI);
     y = r * sin(PI / 2);
 }
+
+
+/*
+ * JSDoc
+ */
+
+/* Inline tag */
+
+/** {@link String} */
+/**
+ * {@link http://example.com | Ex\{am\}ple}
+ */
+/** {@link*/
+
+
+/* Type */
+
+/** {String} */
+/**
+ * {Foo.B\{a\}r}
+ */
+/** {number*/
+
+
+/* Block tag */
+
+// No arguments
+/** @constructor */
+/**
+ * @deprecated since 1.1.0
+ */
+/** @public*/
+
+// Generic argument
+/** @default 3.14159 */
+/**
+ * @tutorial tutorial-1
+ */
+/** @variation 2*/
+
+// Event name argument
+/** @fires earthquakeEvent */
+/**
+ * @listens touchstart
+ */
+/** @event newEvent*/
+
+// Keyword argument
+/** @access protected */
+/**
+ * @kind module
+ */
+/** @access private*/
+
+// Name/namepath argument
+/** @alias foo */
+/**
+ * @extends bar
+ */
+/** @typeParam T*/
+
+// Type and name arguments
+/** @param {String} name - A \{chosen\} \@name */
+/**
+ * @member {Object} child
+ */
+/** @property {number} num*/
+
+// Borrows block tag
+/** @borrows foo as bar */
+/**
+ * @borrows foo as
+ */
+/** @borrows foo*/
+
+// Todo block tag
+/** @todo write more/less test cases */
diff --git a/tests/syntax-highlighting/file.ts b/tests/syntax-highlighting/file.ts
index 07f9ef08..f805a009 100644
--- a/tests/syntax-highlighting/file.ts
+++ b/tests/syntax-highlighting/file.ts
@@ -1384,3 +1384,80 @@ with (Math) {
     x = r * cos(PI);
     y = r * sin(PI / 2);
 }
+
+
+/*
+ * JSDoc
+ */
+
+/* Inline tag */
+
+/** {@link String} */
+/**
+ * {@link http://example.com | Ex\{am\}ple}
+ */
+/** {@link*/
+
+
+/* Type */
+
+/** {String} */
+/**
+ * {Foo.B\{a\}r}
+ */
+/** {number*/
+
+
+/* Block tag */
+
+// No arguments
+/** @constructor */
+/**
+ * @deprecated since 1.1.0
+ */
+/** @public*/
+
+// Generic argument
+/** @default 3.14159 */
+/**
+ * @tutorial tutorial-1
+ */
+/** @variation 2*/
+
+// Event name argument
+/** @fires earthquakeEvent */
+/**
+ * @listens touchstart
+ */
+/** @event newEvent*/
+
+// Keyword argument
+/** @access protected */
+/**
+ * @kind module
+ */
+/** @access private*/
+
+// Name/namepath argument
+/** @alias foo */
+/**
+ * @extends bar
+ */
+/** @typeParam T*/
+
+// Type and name arguments
+/** @param {String} name - A \{chosen\} \@name */
+/**
+ * @member {Object} child
+ */
+/** @property {number} num*/
+
+// Borrows block tag
+/** @borrows foo as bar */
+/**
+ * @borrows foo as
+ */
+/** @borrows foo*/
+
+// Todo block tag
+/** @todo write more/less test cases */
diff --git a/tests/syntax-highlighting/file.tsx b/tests/syntax-highlighting/file.tsx
index 35962a15..31a09b6d 100644
--- a/tests/syntax-highlighting/file.tsx
+++ b/tests/syntax-highlighting/file.tsx
@@ -1489,3 +1489,80 @@ with (Math) {
     x = r * cos(PI);
     y = r * sin(PI / 2);
 }
+
+
+/*
+ * JSDoc
+ */
+
+/* Inline tag */
+
+/** {@link String} */
+/**
+ * {@link http://example.com | Ex\{am\}ple}
+ */
+/** {@link*/
+
+
+/* Type */
+
+/** {String} */
+/**
+ * {Foo.B\{a\}r}
+ */
+/** {number*/
+
+
+/* Block tag */
+
+// No arguments
+/** @constructor */
+/**
+ * @deprecated since 1.1.0
+ */
+/** @public*/
+
+// Generic argument
+/** @default 3.14159 */
+/**
+ * @tutorial tutorial-1
+ */
+/** @variation 2*/
+
+// Event name argument
+/** @fires earthquakeEvent */
+/**
+ * @listens touchstart
+ */
+/** @event newEvent*/
+
+// Keyword argument
+/** @access protected */
+/**
+ * @kind module
+ */
+/** @access private*/
+
+// Name/namepath argument
+/** @alias foo */
+/**
+ * @extends bar
+ */
+/** @typeParam T*/
+
+// Type and name arguments
+/** @param {String} name - A \{chosen\} \@name */
+/**
+ * @member {Object} child
+ */
+/** @property {number} num*/
+
+// Borrows block tag
+/** @borrows foo as bar */
+/**
+ * @borrows foo as
+ */
+/** @borrows foo*/
+
+// Todo block tag
+/** @todo write more/less test cases */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]