Tuesday, May 05, 2009

Documenting RFC implementations

Just wanted to document how I am using the existing documentation such as IETF RFCs and Internet-Drafts in my 39 Peers project. You can looks at some samples at here or here.

I wrote a htmlify.py script. The script uses the SilverCity python package to decorate the base python code. To include the documentation from RFCs, the script interprets the python source code to identify lines such as

# @implements RFC2617 (HTTP auth)

If found, it downloads the particular RFC from IETF website, removes any formatting empty lines such as near page breaks, and numbers all the pages and lines. It then stores the resulting file as a text document which you can lookup and use in your documentation.

Furthermore, the script identifies lines such as

# @implements RFC2617 P3L16-P3L25

If found, the line is replaced by a HTML DIV block with content of the documentation in RFC2617 text file from page-3 line 16 to page-3 line 25.

I find this technique pretty handy, and keeps my decorated source code with inline documentation extracted from RFCs and drafts, instead of I having to write extensive document.

No comments: