fennifith / mdjavadoc Goto Github PK

18.0 2.0 5.0 79 KB

A script that generates markdown javadocs for use in Jekyll and GitHub Pages.

Home Page: https://www.npmjs.com/package/mdjavadoc

License: MIT License

JavaScript 100.00%

javadoc documentation markdown nodejs cli

mdjavadoc's Introduction

Markdown Javadoc is a script that generates markdown javadocs primarily for use in Jekyll and GitHub Pages. It consists of two modules, an API and CLI. If you simply want to generate a set of javadocs in markdown without any scripting, the CLI provides a simple interface with a decent amount of options. If you have a more complex use case, however, it might be more beneficial to look into the API first.

Installation

These are generic installation instructions that are fairly similar for both the API and CLI.

NPM

npm install -g mdjavadoc

From Source

git clone https://github.com/TheAndroidMaster/mdjavadoc
cd mdjavadoc/cli
npm install
sudo npm link

For specific usage instructions, see the README for the API or CLI components.

Functionality

The program works by searching a set of files for javadoc comments, parsing them into a data structure containing the description, tags, and metadata, and then outputting that data into a set of markdown files. For example, a file containing a javadoc comment like the one below would yield the following structure and output...

Javadoc

/**
 * This is a method which does a thing with something and stuff.
 * 
 * @param something		This is something.
 * @param stuff			This is a bunch of stuff.
 * @return			A thing.
 */
public static Object doTheThing(int something, String[] stuff) {
	return null;
}

Data

[
  {
    name: "doTheThing",
    description: "This is a method which does a thing with something and stuff.",
    type: ["public", "static", "void"],
    source: "/package/structure/ClassName.java#L2",
    param: [
      {
        content: "@param something\tThis is something.",
        template: ["Parameter Name", "Description"],
        values: ["something", "This is something."]
      },
      {
        content: "@param stuff\t\tThis is a bunch of stuff.",
        template: ["Parameter Name", "Description"],
        values: ["stuff", "This is a bunch of stuff."]
      }
    ],
    return: [
      {
        content: "@return\t\tA thing.",
        template: ["Returned Value"],
        values: ["A thing."]
      }
    ]
  }
]

Markdown

## [doTheThing](../blob/master/package/structure/ClassName.java#L2)

**Type:** `public` `static` `void`

This is a method which does a thing with something and stuff.

|Parameter Name|Description|
|-----|-----|
|something|This is something.|
|stuff|This is a bunch of stuff.|

**Returned Value:** A thing.

Contributing

Contributions are accepted. See this project's CONTRIBUTING.md for instructions on how to contribute to this project.

mdjavadoc's People

Contributors

Stargazers

Watchers

Forkers

dskvr simon-milleto guzmanfg sergiocarracedo scottmccammon

mdjavadoc's Issues

Annotations Support

Javadocs such as the following...

/**
 * This is a javadoc.
 */
@Nullable
public Object getSomething() {
    return null;
}

...aren't parsed properly; mdjavadoc gets "" as the name since the line after the javadoc doesn't contain the actual declaration. Solution: basically just ignore lines that start with "@" after the javadoc, or add them to the type array.

Templates for Index Files

I need this.

Switch to tokenized parsing

This program currently uses a few regexes to parse the source code, which - well, it works. However, it does apparently re-execute the statement against each source code file for every iteration in the for loop, resulting in a bunch of inefficiency and other fun things. Fun.

Markdown Templates

Thinking of adding support for a "--template" argument which uses the given file as a Jekyll-like template for all of the output markdown files. If I wanted it to get really fun, I could make it an actual jekyll template and give it access to the rest of the data, allowing it to not only display the data in a different format but also put stuff like breadcrumbs at the top of the file, etc.

Replace 'isPublic' option with a more configurable one

Currently isPublic looks specifically for the word "public" in a method's type, but this may not work quite as well for languages other than java. This utility doesn't specifically support other languages, but it doesn't not support them either, and it would be nice to be able to change this to something like "only document final methods" and so on.

AAAAA Generics

Not sure how to support these. A possible solution could be removing content between the "<>" entirely and just ignoring them. Or I could write this thing properly and provide proper support. Meh.

Arguments in Method Names

Pretty simple, just gotta add the first string (split by a space) of each item (split by a comma) in the arguments (surrounded by parentheses) in the declaration line which I'm already getting anyway. The question is if this will affect @see and @link tags or not...

Misidentified Javadocs

To be clear, RegEx isn't exactly the problem here, but it is part of it. I've been told that I shouldn't use RegEx for something like this. I don't know if that advice is valid or not, but it remains the easiest option regardless, so I would prefer not to switch from it if possible.

The RegEx statements should be modified to only accept javadocs that aren't escaped with a preceding "" or contained within a string. Currently, the following lines are identified by the regex statement as a javadoc:

System.out.println("/**");
System.out.println("*/");

Guaranteed, this wouldn't normally show up in an application, but it's still something to look out for.

Breadcrumbs Directories Incorrect

They work fine for index files, but links inside of the index files go to one too many parent directories. Not good. Also, they should ideally point directly to the index files of the directory if indexing is enabled, instead of just going to the folder.

Custom Tags

Idk what use case this falls under, but it's something to consider. Could even be used for something as simple as changing one of the table headers.

Separate RegEx validators for dirs and files

What was I thinking when I wrote this? Nobody puts their java classes in a folder titled "*.java". These should be separate.

Sometimes breaks markdown format in first item

Inline Tags / Class References Don't Actually Work

They just don't do what they're supposed to. Rip.

Mitigate Naming Conflicts

Currently, index files overwrite any doc files that happen to be supplied with the same name as them unless extensions are enabled. As naming the index file something else in this situation would be a little bit of a problem, one solution could be adding the extension to the doc file that is in conflict. It could be possible for this to cause other issues, though. I haven't thought this through yet.

Support "\" for javadoc functions

Apparently some people prefer to use "\" instead of "@" for stuff like \returns Something. and so on. I guess it's faster to type. Maybe it's standardized somewhere I don't know about. Should probably add compatibility for it I guess.