YHack Submission 2019:

Inspiration

The source:

An important part of Computer Science is keeping one's code clean. As many students, engineers, and researchers have discovered is poorly documented code can costs weeks, months, or even years of efforts to work around.

The problem:

Some languages have a fully integrated, optimal system for documenting their code (e.g. Java via. Javadoc). Others, have partial or very little standard in the way of documentation. Even across languages, documentation style and format is different to such a degree that documentation tools are not interchangeable in most circumstances.

The solution:

Write a Universal Documentation Generator (UDG) that dynamically generates documentation based off of preset guidelines. The goal is to provide support for many different types of languages, regardless of style.

Towards that goal, our team at YHack has developed the first stage of such a program. Using the lexer/parser development kit ANTLR4, we created a robust scanner that takes in a file, and parses it for specific tags to create documentation with.

What it does

At this stage, the parser simply identifies multiline comment blocks, and attempts to find and label tags inside for future documentation generation. After it completes it, it will print the tags it was able to identify, and generate a parse tree of the entire file given to it.

How we built it

Although a makefile is included, it is a simple one that only works with the provided yhacktester.cpp file. However, there is a three step process to build (and execute) as needed:

Note that this process has only been done on Unix systems, although in theory it would work on windows.

Create Aliases and Update Classpath: $ cd /usr/local/lib %%% For OSX: $ sudo curl -O https://www.antlr.org/download/antlr-4.7.2-complete.jar %%% Otherwise: $ wget https://www.antlr.org/download/antlr-4.7.2-complete.jar $ export CLASSPATH=".:/usr/local/lib/antlr-4.7.2-complete.jar:$CLASSPATH" $ alias antlr4='java -jar /usr/local/lib/antlr-4.7.2-complete.jar' $ alias grun='java org.antlr.v4.gui.TestRig'
Create an input file to parse: In order for the scanner to work, tags must be indicated by a tab, followed by an @ sign. There are currently 7 tag signs. 'returns' Return Tag to indicate passed/popped values 'param' Parameter Tag (Primarily for functions, subroutines, etc) 'name' The name of the data structure / statement 'author' Who wrote the code being tagged 'date' Important dates for the code (creation, edit, etc.) 'function' Function, subroutine, method, etc Tag 'class' Class Tag 'note' "Nota Bene": An important note to remember 'desc' Description or otherwise explanation of code 'snippet' 'ref' Reference Tag to indicate other (important) files
With input.file written and ready to go in the project directory, Run the following 3 commands:
```
antlr4 UDG.g4
javac UDG*.java
grun UDG program -gui < input.file
```
alternatively, the last line can use -trace instead of -gui

Challenges we ran into

Accomplishments that we're proud of

Backus–Naur Form and Context Free Languages

There's a lot that goes into making a robust parser and lexer, and it's not the easiest thing to pick up in 36 hours. Admittedly we have had some experience in the past, however ANTLR was a completely new experience for us as a team.

First Hackathon

All members on the team decided to go to YHack because they had we had never gone to one before. We didn't know what to expect, and we wanted to see what we could do in a crunch. Now that we've set a bar, we plan on breaking it.

Hardware Issues

One of our team-member's computers stopped charing correctly. After borrowing a multimeter from MLH, we discovered no problems with the cord. We had just enough time to salvage some important documents before our team member's computer died. Although not strictly a software challenge, it was still a part of the experience, and a speed bump in our development plans. Thankfully, the kindness of both MLH and hosts at Yale made that experience much easier than it could have been.

What we learned

Swap tasks when people slow down.

Often people on the team would get stuck on one thing, and we would al swap computers. Not only did fresh eyes look on our bugs and problems, but we also got a break from our mental blocks, and changed gears. A series of nagging bugs got solved this way.

The project was too ambitious for 36 hours

Only after the fact did we discover that we bit off more than we could chew. Although we felt we succeeded in our attempts, it was nonetheless discouraging to not see the tool we planned on designing.

What's next for Documentation Lexer/Parser

Edit parser to work stand alone without dedicated runtime.
Develop data structure to hold data in smaller, more efficient form than parse tree.
Create data base to hold growing list of languages, and necessary data to use UDG with.
attempt to write hello world in as many languages as possible to try and make the code more robust.