mdjavadoc-api

Markdown JavaDoc API

The mdjavadoc-api contains five methods, documented below. Information about the accepted parameters and the behavior of these functions can be found in the project README.

Installation

This is fairly simple.

npm install mdjavadoc-api

Usage

Using the API in your application is pretty easy. For example, this program will parse the file "index.js" and output the resulting markdown to "out.md":

const _mdjd = require('mdjavadoc-api');
_mdjd.generateMarkdownFile("index.js", "out.md");

Another example, this one simply parses "index.js" and prints the parsed data in the console:

const _mdjd = require('mdjavadoc-api');
console.log(_mdjd.parseFile("index.js"));

Options

The options argument on each method is simply an object containing optional arguments which can change the result of the program. These options function as stated below:

Option Name	Type	Description
template	file (string)	Uses the file as a template to generate markdown, replacing occurences of {{ content }} with the generated docs.
reg	RegExp	A regular expression to filter out unwanted files (defaults to /^(?!\.).*/, or "any file that does not begin with a .").
regdir	RegExp	reg but for directories.
extensions	boolean	Whether to include the file extensions in the generated content (setting this to true will name files "ClassName.java.md" instead of just "ClassName.md")
sourcePrefix	string	A string to start all source code URLs with. Defaults to "..". For example, a link to "/api/index.js#L50" will become "../api/index.js#L50".
breadcrumbs	boolean	Whether to add "breadcrumbs" to the top of each file for navigation.
breadcrumbsChar	string	The character to separate breadcrumbs with - defaults to " > ".
index	boolean / string	Whether to generate an index file containing all of the generated docs, and (optionally) the name of the file - defaults to "README.md". By default, this option also generates files for internal directories which look into a smaller amount of folders specified by indexLength.
indexLength	integer	How many directories internal index files should look into - defaults to 3. Setting this value to 0 disables index files for internal directories.
indexExtensions	boolean	Whether to include file extensions (.md, etc) in index files.
indexTemplate	file (string)	A template but for index files. Works almost exactly the same way.

Documentation

Yes, this program has written its own documentation.

setTag

Type: function

Change the template for one of the preset tags. The default tags are defined as:

• author: ["Name"]
• version: ["Current Version"]
• param: ["Parameter Name", "Description"]
• "return": ["Returned Value"]
• exception: ["Exception", "Description"]
• throws: ["Exception", "Description"]
• see: ["Reference"]
• link: ["Reference"]
• since: ["Version"]
• deprecated: ["Deprecation"]

Parameter Name	Description
tag	The name of the tag (without the leading '@').
template	The template to use for the tag (a string array).

Returned Value: An object containing all of the current tags.

generateMarkdownFiles

Type: function

Generates a set of markdown docs from the files in a directory.

Parameter Name	Description
dir	The directory to generate the docs from.
out	The directory in which to place generated files.
options	Optional arguments.

generateMarkdownFile

Type: function

Generates a markdown doc from the specified file.

Parameter Name	Description
file	The file to generate the docs from.
out	The file to output the markdown into.
options	Optional arguments.

formMarkdown

Type: function

Form basic markdown from an array of parsed data.

Parameter Name	Description
data	The parsed data (returned by parseFile) to generate markdown from.
options	Optional arguments.

Returned Value: A string of the markdown formatted docs.

parseDirectory

Type: function

Parses docs for all of the files in a directory.

Parameter Name	Description
dir	The starting directory to parse files from.
prefix	Internally used prefix to append to package names.
reg	A regex statement to match file names to.

Returned Value: An array of the docs fetched from each file.

parseFile

Type: function

Parses the docs in a specific file. Docs are formatted as follows:

{ 
  name: "methodName", 
  description: "This method does a thing with something and somethingelse.", 
  type: ["function"], // basically an array of anything that comes before the method name 
  source: "/package/structure/ClassName.java#L247", 
  param: [ // all tags are added to the map 
    { 
      content: "@param something The thing for the stuff.", 
      template: ["Parameter Name", "Description"], 
      values: ["something", "The thing for the stuff."] 
    }, 
    { 
      content: "@param somethingelse The other thing for the stuff.", 
      template: ["Parameter Name", "Description"], 
      values: ["somethingelse", "The thing for the stuff."] 
    } 
  ] 
} 

Parameter Name	Description
file	The file to parse docs from.
prefix	The prefix to add to the doc packages.
options	Optional arguments.

Returned Value: An array of the parsed docs for the file.