Merge pull request #426 from derms/dev

added example for using jsdoc with ml-gradle project

Author: rjrudin

examples/jsdoc-project/.gitignore

@@ -0,0 +1,4 @@
+.gradle
+.idea
+build
+node_modules

examples/jsdoc-project/README.md

@@ -0,0 +1,26 @@
+## Overview
+
+Example of how to use [jsdoc](http://usejsdoc.org/) in MarkLogic project
+
+This project uses the [JSDoc Gradle Plugin](https://github.com/liferay/liferay-portal/tree/master/modules/sdk/gradle-plugins-jsdoc) to run the jsdoc task
+
+
+## Usage
+
+All of the configuration is captured in the __build.gradle__ file and the __jsdoc.json__ file. To test this, clone this repoitory and execute the command below in this directory 
+
+```
+gradle generateJsDoc
+```
+
+This will generate jsdoc for the code in __src/main/ml-modules/lib__
+
+The html documentation will be generated in __build/docs/jsdoc__
+
+## Customize
+
+To customise the jsdoc output, you can modify the __jsdoc.json__ file. Refer to the http://usejsdoc.org/about-configuring-jsdoc.html site for details on how to configure this.
+
+To customise the jsdoc task generator, please customize the __generateJsDoc__ task in the __build.gradle__ file. Refer to the [JSDoc Gradle Plugin](https://github.com/liferay/liferay-portal/tree/master/modules/sdk/gradle-plugins-jsdoc) site for details on how to configure this.
+
+

examples/jsdoc-project/build.gradle

@@ -0,0 +1,21 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath 'commons-io:commons-io:2.6'
+    }
+}
+
+plugins {
+  id "com.marklogic.ml-gradle" version "3.11.0"
+  id "com.liferay.app.jsdoc" version "2.0.19"
+}
+
+
+task generateJsDoc(type:com.liferay.gradle.plugins.jsdoc.JSDocTask) {
+    configuration = project.resources.text.fromFile(file("jsdoc.json"))
+    destinationDir = "build/docs/jsdoc"
+    sourceDirs = file("src/main/ml-modules/lib")
+} 

examples/jsdoc-project/jsdoc.json

@@ -0,0 +1,17 @@
+{
+    "plugins": [],
+    "recurseDepth": 10,
+    "source": {
+        "includePattern": ".+\\.s?js(doc|x)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    }
+}

examples/jsdoc-project/src/main/ml-modules/lib/sample.sjs

@@ -0,0 +1,20 @@
+/**
+ * Sample Module
+ * 
+ * @module "/sample.sjs"
+ */
+module.exports = {
+    /**
+     * Returns "Hello " plus the str parameter
+     * 
+     * @example
+     * const sampleLib = require("/sample.sjs")
+     * // returns "Hello World"
+     * sampleLib.hello("World")
+     * 
+     * @param {string} str the string to say hello to
+     */
+    hello: function(str) {
+        return `Hello ${str}` 
+    }
+}