docs(*): add docstrings - #37 (#38)

* chore: Eslint setup and configuration for js-docs - #37

* docs: Added docstring for functions - #37

* chore: Eslint setup and configuration for js-docs - #37

.eslintrc.json

@@ -16,7 +16,7 @@
       "jsx": true
     }
   },
-  "extends": ["eslint:recommended", "plugin:react/recommended"],
+  "extends": ["eslint:recommended", "plugin:react/recommended", "plugin:jsdoc/recommended"],
   "rules": {
     "arrow-parens": ["error", "as-needed"],
     "comma-dangle": ["error", "always-multiline"],
@@ -29,7 +29,16 @@
     "no-multi-spaces": "error",
     "no-trailing-spaces": "error",
     "quotes": ["error", "single"],
-    "semi": ["error", "always"]
+    "semi": ["error", "always"],
+    "require-jsdoc": ["warn", {
+        "require": {
+          "FunctionDeclaration": true,
+          "MethodDefinition": true,
+          "ClassDeclaration": true,
+          "ArrowFunctionExpression": true,
+          "FunctionExpression": true
+        }
+    }]
   },
   "settings": {
     "react": {

package.json

@@ -16,8 +16,8 @@
     "build:dev": "webpack --mode development --https false",
     "build-dev": "webpack --mode development --https false && echo . && echo . && echo . && echo Please use 'build:dev' instead of 'build-dev'.",
     "dev-server": "webpack-dev-server --mode development",
-    "lint": "eslint **/*.{js,jsx}",
-    "lint:fix": "eslint **/*.{js,jsx} --fix",
+    "lint": "eslint '**/*.{js,jsx}'",
+    "lint:fix": "eslint '**/*.{js,jsx}' --fix",
     "start": "office-addin-debugging start manifest.xml",
     "start:desktop": "office-addin-debugging start manifest.xml desktop",
     "start:web": "office-addin-debugging start manifest.xml web",
@@ -49,6 +49,7 @@
     "copy-webpack-plugin": "^6.0.1",
     "css-loader": "^3.0.0",
     "eslint": "^7.1.0",
+    "eslint-plugin-jsdoc": "^32.3.0",
     "eslint-plugin-react": "^7.16.0",
     "extract-text-webpack-plugin": "4.0.0-beta.0",
     "file-loader": "^4.2.0",

src/components/App.js

@@ -5,6 +5,12 @@ import { Menu } from 'semantic-ui-react';
 import TemplateLibrary from './TemplateLibrary';
 import './App.css';
 
+/**
+ * Returns the App component which is rendered.
+ *
+ * @param {boolean} isOfficeInitialized Checks whether office is intialized or not
+ * @returns {React.FC} React component
+ */
 const App = ({ isOfficeInitialized }) => {
   const [activeNav, setActiveNav] = useState('library');
   const [openOnStartup, setOpenOnStartup] = useState(false);
@@ -16,10 +22,22 @@ const App = ({ isOfficeInitialized }) => {
     }
   }, [isOfficeInitialized]);
 
+  /**
+   * Sets the active nav item in the navbar.
+   *
+   * @param {MouseEvent} event    Mouse click event
+   * @param {object}     obj      An object
+   * @param {string}     obj.name Name of the event
+   */
   const handleClick = (event, { name }) => {
     setActiveNav(name);
   };
 
+  /**
+   * Sets whether add-in should load by default on MS Word startup.
+   *
+   * @param {MouseEvent} event Mouseclick to see if checkbox is clicked
+   */
   const handleStartupState = event => {
     Office.context.document.settings.set('Office.AutoShowTaskpaneWithDocument', event.target.checked);
     setOpenOnStartup(event.target.checked);

src/components/TemplateLibrary/index.js

@@ -14,11 +14,19 @@ import triggerClauseParse from '../../utils/TriggerClauseParse';
 const CUSTOM_XML_NAMESPACE = 'https://accordproject.org/';
 const XML_HEADER = '<?xml version="1.0" encoding="utf-8" ?>';
 
+/**
+ * Template library Renderer.
+ *
+ * @returns {React.FC} Template library
+ */
 const LibraryComponent = () => {
   const [templates, setTemplates] = useState(null);
   const [overallCounter, setOverallCounter] = useState({});
 
   useEffect(() => {
+    /**
+     * Loads the template library from https://templates.accordproject.org/ and stores them in the state.
+     */
     async function load() {
       const templateLibrary = new TemplateLibrary();
       const templateIndex = await templateLibrary
@@ -30,6 +38,11 @@ const LibraryComponent = () => {
     load();
   }, []);
 
+  /**
+   * Renders an uploaded template.
+   *
+   * @param {MouseEvent} event event containing the file object
+   */
   const onUploadTemplate = async event => {
     const fileUploaded = event.target.files[0];
     try {
@@ -43,6 +56,9 @@ const LibraryComponent = () => {
   };
 
   useEffect(() => {
+    /**
+     * Initializes the document by fetching the templates whose identifier is stored in CustomXMLPart.
+     */
     async function initializeDocument() {
       Office.context.document.customXmlParts.getByNamespaceAsync(CUSTOM_XML_NAMESPACE, result => {
         if (result.status === Office.AsyncResultStatus.Succeeded) {
@@ -79,6 +95,13 @@ const LibraryComponent = () => {
     }
   }, [templates]);
 
+
+  /**
+   * Sets up a template for rendering.
+   *
+   * @param {object} ciceroMark Ciceromark JSON
+   * @param {object} template   Template object
+   */
   const setup = async (ciceroMark, template) => {
     await Word.run(async context => {
       let counter = { ...overallCounter };
@@ -130,6 +153,12 @@ const LibraryComponent = () => {
     });
   };
 
+  /**
+   * Converts a template text to CiceroMark JSON.
+   *
+   * @param {object} template The template object
+   * @returns {object} CiceroMark JSON of a template
+   */
   const templateToCiceroMark = template => {
     const sampleText = template.getMetadata().getSample();
     const clause = new Clause(template);
@@ -138,6 +167,11 @@ const LibraryComponent = () => {
     return ciceroMark;
   };
 
+  /**
+   * Fetches templateIndex from https://templates.accordproject.org/, load the template, and save template details to CustomXML.
+   *
+   * @param {object} templateIndex Details of a particular template like URL, author, displayName, etc.
+   */
   const loadTemplateText = async templateIndex => {
     // URL to compiled archive
     const template = await Template.fromUrl(templateIndex.ciceroUrl);
@@ -147,6 +181,11 @@ const LibraryComponent = () => {
     saveTemplateToXml(templateIdentifier);
   };
 
+  /**
+   * Saves the template details to CustomXML.
+   *
+   * @param {string} templateIdentifier Identifier for a template
+   */
   const saveTemplateToXml = templateIdentifier => {
     Office.context.document.customXmlParts.getByNamespaceAsync(CUSTOM_XML_NAMESPACE, result => {
       if (result.status === Office.AsyncResultStatus.Succeeded) {
@@ -186,6 +225,11 @@ const LibraryComponent = () => {
     });
   };
 
+  /**
+   * Redirects to the template URL.
+   *
+   * @param {object} template Template object
+   */
   const goToTemplateDetail = template => {
     const templateOrigin = new URL(template.url).origin;
     const { name, version } = template;

src/error/BadFile/index.js

@@ -3,7 +3,11 @@ import * as ReactDOM from 'react-dom';
 import { Message } from 'semantic-ui-react';
 
 import './index.css';
-
+/**
+ * Renders a message when a bad file is uploaded.
+ *
+ * @returns {React.FC} Bad file component
+ */
 const BadFile = () => (
   <Message negative className="message-container">
     <Message.Header>Bad file uploaded</Message.Header>

src/index.js

@@ -4,7 +4,11 @@ import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 
 let isOfficeInitialized = false;
-
+/**
+ * Renders a react component.
+ *
+ * @param {React.ReactDOM} Component React component to be rendered
+ */
 const render = Component => {
   ReactDOM.render(
     <AppContainer>
@@ -14,7 +18,7 @@ const render = Component => {
   );
 };
 
-/* Render application after Office initializes */
+/* Renders application after Office initializes */
 Office.initialize = () => {
   isOfficeInitialized = true;
   render(App);

src/utils/AttachVariableChangeListener.js

@@ -1,3 +1,8 @@
+/**
+ * Attaches listener to content controls so that similar instances of variables are updated simultaneously.
+ *
+ * @param {string} title Title of the variable
+ */
 const attachVariableChangeListener = title => {
   Office.context.document.bindings.addFromNamedItemAsync(title, Office.CoercionType.Text, { id: title }, res => {
     if (res.status === Office.AsyncResultStatus.Succeeded) {
@@ -18,6 +23,12 @@ const attachVariableChangeListener = title => {
   });
 };
 
+
+/**
+ * Updates value of all the instance of variables with the same tags when one of them is manually modified.
+ *
+ * @param {Office.BindingDataChangedEventArgs} event Provides information about the binding that raised the DataChanged event
+ */
 const variableChangeListener = event => {
   const { binding } = event;
   // ID of the binding the user changed