steventhanna / argot

Parse documentation from codebases into Markdown for easy doc creation.

Argot

Parse documentation from codebases into markdown for easy doc creation. Argot is inspired by the traditional JavaDoc system.

Motivation

Maintaining large systems in differenet languages brings its own set of unique challenges, especially when maintaining documentation for those systems. Different documentation systems degrade the overall quality of the codebase, while hindering the productivity of developers. Argot attempts to rectify this by providing a single documentation style that can support any language, and dumps the resultant documentation to Markdown.

The Name?

The defintion of argot is "the jaron or slang of a particular group or class". Seems like a pretty fitting name for a documentation system.

Warning

This is still a work in progress, so things might break. Submitting a bug report is the best way to help me identify issues.

Argot in Action

Check out Argot's Wiki where Argot is run against this repo.

Installation (for use)

Install using Cargo

cargo install argot

Installation (for development)

• Clone the repo
• Ensure Rust / Cargo is installed
• In the command line ...

cargo build

cargo run -- --help

Build for relase

cargo build --release

CLI Arguments

Argot 0.2.0
Steven Hanna <[email protected]>
Parse documentation from codebases into Markdown for easy doc creation.

USAGE:
    argot [FLAGS] --destination <DESTINATION> --origin <ORIGIN>

FLAGS:
    -h, --help         Prints help information
    -r, --recursive    Recursively walk the file tree parsing
    -V, --version      Prints version information

OPTIONS:
    -d, --destination <DESTINATION>    Sets a custom destination path for rendered markdown files
    -o, --origin <ORIGIN>              Sets the origin of where Argot should start parsing from

Example

argot -o /src -d /docs -r

The Markdown

All Supported Languages

The system is being designed to adjust parsing based on the supplied commenting style. Whether it be for Slash based languages like Java of C, to other commenting systems used in Python or Haskell. Instead of designing a specific language class and filling in the holes provided by the abstract class, new languages would be supplied through a simple constructor.

All tags must include a type tag.

Java, Rust, C++, JS

/**
* @type :: FUNC
* @name :: test
*/

Python

'''
@type :: example
@name :: test
@end
'''

NOTE: Markdown can be included within the documentation itself, and it will be rendered on the final page.

Types

• FUNC - Tag for a function or method
• VAR - Tag for a variable
• CLASS - Tag for a class

Beginning the file

When beginning the file, you can use any of the following in any combination at the start of your class, before any declarations.

@name :: - The classname for the file

@description :: - Description of what the file does in relation to the project as a whole

@date :: - Date file was last modified

@version :: - Current version of file

@author :: - the author of the file. Multiple authors should be separated by a comma

@see :: - provides a link to another file in reference

@child :: - indicate the child of the class. Multiple children should have their own @child tag

@parent :: indicate the parent of the class

@note :: - notes any important information relevant to the file

Java

/**
* @type :: CLASS
* @name :: Example File
* @author :: Steven Hanna, Other People
* @date :: 7/25/16
* @version :: 0.1.0
*/

Python

'''
@type :: CLASS
@class :: Example File
@author :: Steven Hanna, Other People
@date :: 7/25/16
@version :: 0.1.0
'''

Methods

Note: The actual body of the method is not analyzed, just the commented documentation.

@name :: - the name of the method.

@description :: - description of the method in relation to the rest of the class. The description can span multiple lines

@author :: - author of the method

@date :: - date method was last updated

@param :: - one parameter the method takes. For each parameter, an new @param is used.

@return :: - what the method returns. If void, omit this doc.

@exception :: - an exception that might be thrown from this method

@thrown :: - an error that might be thrown from this method

@see :: - provides a link to external documentation

@note :: - notes any important information relevant to the method

/**
* @type :: FUNC
* @name :: sampleMethod
* @description :: Provides a sample method for this example.
* Overflow text can continue here
* @param :: String text - text to be returned
* @return :: String text - text that is returned
*/
public String sampleMethod(String text) {
  ...
  return text;
}

Variables / Instance Variables

Like methods, documentation for variables must begin before the variable is declared. Variables should only be documented upon declaration.

@name - the name of the instance variable

@description - description of the variable in relation to rest of the class

@see - provides a link to external documentation

/**
* @type :: VAR
* @name :: exampleInt
* @vartype :: the type of the variable
* @description :: example integer variable
*/
private int exampleInt;

argot's Issues

Add Python Support

Add support for the Python language

TODO

• Add HashLangauge.java that models SlashLanguage.java NOTE: Must implement Language
• Add HashComment.javathat models SlashComment.java NOTE: Must implement Comment

Identify methods from Java

Identify methods in Java files to be parsed through Argot.

Add Multi-Threading for increased performance

Auto Updater

Create an Auto Update system

Update README and Docs

Update README and docs to document the new version of Argot.

• README
• Wiki
• CONTRIBUTING.md

Can not extract multiple lines of text

For some reason, the system does not like this method... And this method is kinda important.

public String[] extractMultiple(String tag) {
    ArrayList<String> temp = new ArrayList<String>();
    int totalTags = 0;
    // Find tags
    for(int i = 0; i < header.size(); i++) {
      // Tag exists
      if(header.get(i).contains(tag)) {
        temp.add(header.get(i));
        totalTags++;
        // Check for multi-line
        if(nextLineEscapePosition(i) != i) {
          // Multi-line == true
          for(int j = i; j < nextLineEscapePosition(i); j++) {
            temp.add(header.get(j));
          }
        }
      }
    }
    // Declare array
    String[] array = new String[totalTags];
    // Combine the multi-line
    for(int i = 0; i < array.length; i++) {
      for(int j = 0; j < temp.size(); j++) {
        if(temp.get(j).contains("@")) {
          array[i] = extractSingle(tag, temp.get(j), true);
        } else {
          array[i] += extractSingle(tag, temp.get(j), false);
        }
      }
    }
    return array;
  }

Add Support for Todo's

New Language Constructor

Need a new constructor for Language.java that can handle HTML like syntax, with a beginning tag, and an ending tag.

Add a Spell Checker Option

Have the ability to spell check the docs looking, returning errors and suggestions.

Check Here

Add Markdown Code Support

Preserve the line structure for markdown segments.

Add different Logging Levels

For --verbose, --quiet