-
-
Notifications
You must be signed in to change notification settings - Fork 320
MichaelTao
A solution to modern problems with synchronizing source code and documentation
- Email: [email protected] / [email protected]
- MSN: [email protected]
- EST time
During software development, some sort of documentation is necessary to make the source code readable to the make debugging easier and to make the code easier to learn for later programmers. Currently, documentation is formed through comment blocks throughout code, and while editing the documentation through the code is possible, it is impossible to edit the documentation from the actual documentation itself without causing a discrepancy between what the documentation generated by the source code and the documentation that has been edited. Therefore I am proposing to write software to allow for edits to the documentation generated by the source code and from the actual documentation without causing discrepancies between the automatically generated documentation and the current version of the documentation.
The benefits to such an application would be that a single project implementing several programming languages could have it's documentation automatically updated the moment the update is performed and the source code commenting being automatically updated from changes in the documentation.
For this project, there would need to be a core script, which would be initialized on updates to either the source code or documentation for a project, and then two types of modules to interact with any project: a module to deal with updates and modifications of the source code and a module to deal with any given type of documentation (such as wiki markups), which will all be utilized as modules to the core. The goal of this project would be to generate a core for which to manage the bidirectional editing of the source code / documentation and to define how to write these three types of modules.
Since this project would be a new project, not directly related to any existing code, and there aren't any foreseeable compatibility issues with existing code.
Continuous Documentation would update upon a repository updating or the documentation for the project changing, though upon any change in the documentation, an it would put it onto a list for administrators to check, and then they would have to manually update the source onto the repository.
The core script for Continuous Documentation runs for each update on the source code or documentation for a project. If it detects that the source code has changed, it loads the module which detects if the commenting has changed, and modifies the internal MoinMoin wiki copy of the documentation. The particular module will be decided upon by the file extension of the file being edited. Then it loads the modules for all of the supported documentation modules and updates the documentation appropriately. Upon changes to the documentation, it will create the updated internal MoinMoin wiki and the changes to the source code, but place them in a temporary location and added to a "todo list" for administrators of the project to accept/reject the updated versions.
One of the primary strengths of this software will be the fact that it will be highly extensible into any programming language and form of documentation through easy-to-write modules. There are two types of modules, modules to convert the source code into MoinMoin and the vice versa, and modules which will convert MoinMoin into any given form of documentation and vice versa.
For each programming language used in a project implementing Continuous Documentation, there should be a module defining a set of instructions on how to detect blocks of commenting, both for extracting the data for insertion into wiki, but also to give instruction module on how Continuous Documentation should plan to insert information into the source code from the changes in documentation. Examples of “blocks of commenting” would be comments following function declarations or comments located at the beginning of a file describing its contents.
On the other end, the documentation would run through a similar system. Code blocks would be mapped directly onto certain regions of the source code associated with it by some simple user-written instruction module based on the format utilized by any certain type of documentation. For instance, in MoinMoin, MediaWiki, and Trac all use very similar formats such as =title1= [link], so instruction modules could be easily designed to convert them all into MoinMoin and to convert MoinMoin to the other formats.
First I would develop individual modules (Python <-> MoinMoin) in order to have a basis of working code for the project fairly early on. Since internally the project will be dependent on a MoinMoin wiki formatting, it would be cleanest to build something using MoinMoin as a starting point. Writing from Python to Wiki is something which has been done in the past (such as the Python API), so this should be fairly straightfoward. However figuring out how to maintain the code based off the documentation is not something which has been done in the past, and there will likely be some unforseen complications in trying to maintain both the source code and documentation at the same time that will need to be checked upon later on.
After I have an example from which to run everything from, it will be necessary to make this code usable in a real world context. Therefore, after I have something which can modify the source code and documentation wiki, I will write scripts to administrate conforming the differences between the source code and the documentation between Subversion commits and edits to the wiki.
After writing the script, I will only have one source and one wiki type to work with, and since part of the purpose of this project is to allow for multiple languages and wiki types to be used, I will write the modules for Java and the MediaWiki and Javadoc documentation formats.
I expect that there will be a number of small issues to deal with, and I will therefore try to allocate the rest of my time working for GSoC on doing bugfixing and giving myself time to catch up incase I fall behind.
By the end of the GSoC working period I expect I will have written software to do the following:
- A core to detect changes in the source code and documentation and update them appropriately
- Modules to generate the documentation for Python and Java bidirectionally into MoinMoin
- Modules to generate the MediaWiki, and Javadoc I will also document exactly what the software expects for inputs and outputs.
I plan to have the following goals set for each week during the GSoC period.
- week 1: Write a single software to do single direction conversion between Python code and a MoinMoin wiki
- week 2-3: Write the code for converting MoinMoin to Python
- week 4-5: Write the script to maintain the files under Subversion and documentation changes
- week 7: Write the software between Java code and MoinMoin wiki that will convert both directions
- week 8-10: Write software to convert the MoinMoin wiki into MediaWiki and Javadoc in both directions
- week 11-: Bugfixing and finishing things off
I expect to be available to work on this project throughout the whole summer break
I am a first year student at the University of Toronto double majoring in Computer Science and Mathematics. I first coded in Python for a course in AI during high school two years ago at Thomas Jefferson High School for Science and Technology. This will be my first time doing anything open source, though I plan on doing more things in the community in the future.