Coder Social home page Coder Social logo

argot's Introduction

Argot

Status

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 People

Contributors

shannasplk avatar steventhanna avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

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

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;
  }

New Language Constructor

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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.