Skip to content

Latest commit

 

History

History
61 lines (49 loc) · 2.57 KB

README.md

File metadata and controls

61 lines (49 loc) · 2.57 KB
Raw

###Racket-Doc Logo

####Project Description Racket-Doc is a documentation generator for the Racket language. It will extract documentation and specified attributes from source files, and then generate code for a web server and web pages with the extracted data embedded. The web server is by default running on the local host; however, this can easily be modified by changing a single line in the output source file.

####Preparation To write documentation to be analyzed and generated by the application you must use the following syntax, which experienced programmers will recognize as similar to traditional JavaDoc.

#||
 |This procedure does so-and-so
 |
 |@param num This is a number which will have
 |	     something...
 |@return Returns #t if ... else #f
 |#
(define (name-of-proc num)
.
.
.

Note:

  • There should be a one-to-one ratio between procedures/defined variables and documentation; i.e. every procedure and global variable should have documentation. If the code does not have documentation for each procedure and global variable, the procedures displayed in the web page may not align to the correct documentation.
  • Global variables cannot be defined on one line. They should be defined with at least two lines -- for example:
(define five
     5)
  • Do not put other comments on their own line. For example,
(+ 2 4) ;;this adds two numbers

is ok, but

;;this adds two numbers
(+ 2 4)

is not ok.

####Build & Run

Optional: This package includes a css file if you would like more elegant web pages to be generated. If so, copy and paste the directory htdocs (found in Racket-QA/Racket-Doc/) into a directory right above of your output destination directories.

Required: Run master-gui.rkt. Select an option from the radio buttons: file if you wish to process only one .rkt file, or directory if you wish to process all the *.rkt files under a given directory. Select an output destination (directory). The output will be stored to in the location in a file named racketDocOutput.rkt. Run this file.

####** Important Note**

Since there is an almost infinite variety of input the user can give to Racket-Doc, there are obviously limitations -- some of which may be untested. So don't give the project anything too sophisticated to process (for instance, strings with many backslashes in them or regular expressions with many backslashes).

It is suggested to begin with the sample code in the tests folder.