Merge pull request #6 from AbhyudayaSharma/tsdoc

Documentation for Typescript types

Author: AbhyudayaSharma

.editorconfig

@@ -1,3 +1,11 @@
+root = true
+
 [*]
-indent_style = space
+tab_width = 2
+charset = utf-8
 indent_size = 2
+end_of_line = lf
+indent_style = space
+max_line_length = 120
+insert_final_newline = true
+trim_trailing_whitespace = true

.gitignore

@@ -1 +1,4 @@
 node_modules/
+
+# IntelliJ IDEA files
+.idea/

macro.d.ts

@@ -1,16 +1,47 @@
+/**
+ * A Babel plugin macro giving access to git information at compile time.
+ */
 declare module "react-git-info/macro" {
+  /**
+   * Information about a git commit.
+   */
   export interface GitCommitInformation {
+    /**
+     * Date of the commit as a string in strict ISO 8601 format.
+     */
     readonly date: string;
+    /**
+     * Full hash of the latest commit on the active branch.
+     */
     readonly hash: string;
+    /**
+     * Raw commit message.
+     */
     readonly message: string;
+    /**
+     * Abbreviated commit hash with length defined as `core.abbrev` in
+     * {@link https://git-scm.com/docs/git-config | git-config}.
+     */
     readonly shortHash: string;
   }
 
   export interface GitInformation {
+    /**
+     * Tags pointing to the current commit.
+     */
     readonly tags: string[];
-    readonly branch: string;
+    /**
+     * The current git branch. `undefined` if the repository is in a detached HEAD state.
+     */
+    readonly branch?: string;
+    /**
+     * Information about the commit pointed to by `HEAD`.
+     */
     readonly commit: GitCommitInformation;
   }
 
+  /**
+   * Returns information about the current Git state.
+   */
   export default function GitInfo(): GitInformation;
 }

src/GitInfo.macro.js

@@ -1,40 +1,44 @@
 const { createMacro } = require('babel-plugin-macros');
 const { execSync } = require('child_process');
 
-const parseGitLog = (() => {
-  let message = '';
-  let refs = '';
+const parsedGitLog = (() => {
+  let message;
+  let refs;
   const commit = {};
   // only the commit message can have multiple lines. Make sure to always add at the end:
+  // The format is specified in https://git-scm.com/docs/git-log#_pretty_formats
   const logResult = execSync('git log --format="%D%n%h%n%H%n%cI%n%B" -n 1 HEAD')
     .toString()
     .trim()
     .split(/\r?\n/);
   [refs, commit.shortHash, commit.hash, commit.date, ...message] = logResult;
-  commit.message = message.join("\n");
+  commit.message = message.join('\n');
   return {refs, commit};
 })();
 
 const parseRefs = (refs) => {
-  let branch;
+  let branch = undefined;
   const tags = [];
-  refs.split(", ").map((item) => {
-    const isBranch = item.match(/HEAD -> (.*)/);
-    const isTag = item.match(/tag: (.*)/);
+  refs.split(', ').map((item) => {
+    // if HEAD is not detached, the branch is printed out as `HEAD -> branch_name`.
+    // if HEAD is detached, the output becomes `HEAD`.
+    const isBranch = item.match(/^HEAD -> (.*)$/);
+    const isTag = item.match(/^tag: (.*)$/);
 
     if (isTag && isTag.length > 1) {
       tags.push(isTag[1]);
     } else {
       branch = isBranch ? isBranch[1] : branch;
     }
   });
+
   return [branch, tags];
 };
 
 const gitInfo = (() => {
   const ret = {};
   try {
-    const logResult = parseGitLog;
+    const logResult = parsedGitLog;
     [ret.branch, ret.tags] = parseRefs(logResult.refs);
     ret.commit = logResult.commit;
   } catch (e) {