Code Documentation Tool/Website

Planned is a web portal where the customer can upload or import projects which are
written in different programming languages and have those automatically being
documented. Documentation will be hosted on the website and will be presented as
an html/jQuery style document.

1. The Code Parsing Script

The script to parse and analyze the uploaded projects is the heart of this entire
concept.
For the startup, the following code bases shall be parsable:
-

PHP
JavaScript
jQuery (to a certain degree)
CSS (stylesheets)

Further functionality for the following is planned so the code parsing functionality
should be modular and easy to extend:
-

.net/C#
Asp
Pearl
Java (incl. Android and iOS variants)

Parsing and processing a projects code base can be divided into 5 major steps.
1.1Upload a new Project / Refresh an existing Project
For the initial release, a project should be uploaded by dropping a zip file via HTML5
style or upload the traditional way by using a file input, or download files fom a
remote server via ftp or ssh if the customer provides access and path of the project.
Furthermore implementations to clone a git or svn repository, connect to a dropbox
account and similar are planned but should not be included with the initial release.
The actual upload process should be designed as follows:
-

The user creates a quick account (email and password only, no confirmation)
or logs in to an existing account
The user uploads the files. The upload form for the files should have a couple
of options, it should state a checkbox group with filetypes to be documented
as well as an option to document additional file types which are not ending on
the default extensions (i.e. php default extensions .php, .php4, .php5, etc).
Furthermore a checkbox for auto processing should be present, where the
user can skip the authorization of a pending job in case the account status is
sufficient for the uploaded project.
Upon completion of the upload, a job should be stored in the database. The
job status should be pending while the file structure is being discovered.

The user gets the message that his project is being prepared, as soon as the
backend cronjob or deamon is finished discovering the files, the user should
get a notice via email that his project overview is finished. In case the screen
is still open it should simply refresh with the project overview.

1.2Pre Processing Of a Project (Authorization)

Any pending uploaded projects have their file structures discovered by a
cronjob/deamon. The pricing structure is graded by the amount of files contained in
a project, so the cronjob has to discover every file included in the code base and list
it in the database.
The following details about each and every file have to be stored along with the job:
-

file type (i.e. php, js, html, etc)

file location and file name (i.e. /application/controllers/controller.php)
the size of the file in kilobytes
the last modification date
the number of lines of the file
the encoding of the file (utf-8, iso, windows 1312, etc)
the actual contents of the file

All discovered files then have to be consolidated in a project overview. The project
overview should feature the following information:
-

Total number of project files

Number of files per file type (i.e. 100 .php files, 50 .js files, etc)
Current account subscription and if the current plan is sufficient to hold the
project.
Estimated time to finish the project
Option to select/deselect files to include within the documentation
Option to upgrade the account plan to hold the project

1.3Processing of a Project
The processing of a project is handled by a cronjob or deamon once a pending
project has received authorization. Several data has to be gathered on the
processed files and stored in the database. Following is an overview with included
examples on what code elements have to be parsed and how they have to be
stored (for good normalization, probably more values will have to be stored with the
elements). Also the decision on how to store the different elements (1 table,

multiple tables, reference by id across multiple tables, reference by id and type

across single table etc)
-

Documentation Blocks:
Documentation blocks describe a file, class, function, variable, constant or
any other block of code. For an example about documentation blocks, and
what elements have to be parsed see files example-documentation-blocksclass.php, example-documentation-blocks-functions.php, exampledocumentation-blocks-static.php
1.4Output and visualization of a Project
Mainly tbd, should be mostly similar to the clean template of phpdoc

2. The Website
2.1. User Control System
The website has to allow users to register for different types of accounts:
- Free Users (Can use the website for limited purposes)
- Regular Users (Have a paid subscription)
The user control system has to feature all common functionalities:
- optional 2 step authentification (using text message through twilio)
- Change user details, newsletter preferences, notification preferences
- Change password/email address
- Recover lost password
- Show invoices
- Manage billing methods (credit card, bitcoin or PayPal - recurring)

2.2 Static Website

The main website will be static content and has yet to be defined.

2.3 Subscriptions
Subscriptions are yet to be completely defined but will look as follows:
- Free User: ($0/month) - Up to one code project with up to 10 documented
files
- Basic: ($10/month) - Up to one code project with up to 50 documented files
- Advanced: ($20/month) - Up to 3 code projects with up to 100 documented

files
- Professional: ($50/month) - Up to 5 code projects with up to 200
documented files
- Premium: ($100/month) - Up to 10 code projects with up to 500 documented
files
- Enterprise/Custom - After contact - individual solutions
All subscriptions should be available as a 1 month, 3 month, 6 month and 1 year
subscription giving a level of discount yet to be defined - for example 10%, 20%,
30%, 40%