REST Document Generator Project Proposal

Personal Information

Name: Nyah Watad Check

IRC Nick: Ch3ck, Ch3ck_

Background Information

I am a third year Computer Engineering student of the University of Buea and one of the two first GSoC participants in Francophone Africa; worked with BRL-CAD in GSoC 2013, participated in the Google Doc Camp where I documented the BRL-CAD, OpenMRS and GNome projects. Participated as an X.org Evoc participant with X.org in 2014. I participated in as a Mentor in the 2014 Google Code-In for BRL-CAD.

Programming Background

X.org Evoc Participant, X.org, July – October 2014

Added Shatter Support to the X server project using Xephyr.
Clip Impedance layer to Xephyr and ran unit tests like Xts fixing bugs

Google Summer of Code Participant, BRL-CAD, April - September 2013

Implemented a pull routine to reverse the effects of a push on Geometry, integrating command into MGED interface. (C, XML, 500+ lines of code)
Tested the polynomial and matrix math routines, improving the speeds of the inverse matrix and matrix determinant routines by over 10%. (C, 300+ lines of code)
Integrated the xpush routine which pushes objects having more than a single matrix transformation into the push which pushes object matrix transformations to leaf nodes. ( C, 1000 lines of code.)

Book Sprint Participant, Google Doc Camp, October 2013

Participated in creating a contributors guide to BRL-CAD which will encourage a greater number of contributors to working on the BRL-CAD project.

SKILLS

Languages: C(Excellent), Java( Excellent ), C++( Beginner), Bash(Excellent), SQL(Proficient)

Tools: Secure Shell, subversion, Git, Linux, Netbeans, gdb, valgrind.

Project Information

Implementing the REST Document Generator Project

Synopsis, Brief Summary

This project aims at creating a more robust and easy to use REST documentation generator for OpenMRS. Furthermore, documentation will be improved to list differences in resource representations or available search parameters based on installed modules or OpenMRS. Also developer support for adding documentation to any field of resource will be created with ease of export of current documentation in wiki format from the running module, making it more user-friendly.

Detailed Project Description

Introduction

The OpenMRS webservices.rest module provides the RESTful web service and is the most actively developed and most used OpenMRS module. It is used by modern UIs and external services; it's documentation generated and it does not cover all exposed features.

This poses some limitations to OpenMRS implementers and developers since documentations is a very big problem with most open source projects.

Below is my detailed proposal which shows how I plan on implemeting the above features making OpenMRS REST Documentation more robust and increasing documentation flexi bility which gives developers more control over generated documentation.

Features

Below are the set of features I plan on implementing for the REST API this summer in order to increase performance and completeness of the OpenMRS REST Documentation.

Documentation for Search Handlers

OpenMRS currently implements search handlers to provide custom search capabilities to any resource. Search requests are delegated to search handlers if required and optional parameters matched. They all implement the search interface(webservices.rest/omod-common/src/main/java/org/openmrs/module/webservices/rest/web/resource/api/SearchHandler.java). The Doc generator receives several SearchHandler objects through a base url link, passing them to the ResourceDocCreater class which then generates the documentation returning a resourceDocMap containing the map of resource names, associated documentation objects with resource representations.

Add Support for Differences in Representations

As an improvement to doc generation of search handlers, documentation will be generated based on installed OpenMRS version on localhost.

Developer Support for Documentation Creation

The DelegatingResourceDescription class gives the capability of adding custom documentation for any field of a resource. This object can be passed to the ResourceDocCreator object through the fillRepresentations() method which can then be passed through the createDoc() to autogenerate the added documentation for the given resource.

Support for Documentation Export

I plan on implementing a RESTHelper service class implementation of the generated documentation to enable export to XML or any any other wiki format together with a corresponding WUI command from the REST Administration interface for documentation export.

I am still to verify better together with input from mentors to adequately implement these features, but from my current research and understanding I see this is possible.

Testing and Verification

Test driven development will be key in implementing this project. With implementing the tool for extracting and documenting Search handlers, I will write unit tests to check the generation of Search handler documentation.

Also, any bugs coming up during this process will be fixed and documentation of this work done during development since the REST Module is actively developed and this will keep other developers informed on any changes taking place in the REST module.

Deliverables

Tool for extraction and documentation of Search Handlers.
Improve documentation to list differences in resource representations or available search parameters based on installed OpenMRS version
Support Developer documentation of any field of a resource
Support for export of generated documentation to wiki format from running module.

Development Schedule/Timeline

This is a tentative plan which will be modified and developed as GSoC proceeds.

May 17 – May 23( 1 week)

Study papers on this topic
Discuss with developers on implementation specifics and further clarifications on REST Document generator implementation.
Creation of tool for extracting and documenting search handlers on the REST API.
Add parameter support for Search Handler as specified by SearchConfig
Testing, debugging and documentation.
Unit testing of new Search Handler with SearchConfig parameters.
Testing degenerate cases.

May 24 – June 13 ( 3 weeks)

June 14 – June 20( 1 week)

June 21 – July 4 ( 2 Weeks) Mid Term Evaluations

Add functionality for listing differences in resource representations
Add support for listing supported search parameters based on installed OpenMRS modules.

July 5 – July 11( 1 week)

Unit testing and debugging.
Adding documentation to REST API

July 12 – July 25 ( 2 weeks)

Create tool to enable developers add documentation for any field of a resource.
Port added documentation to autogenerated documentation.
Testing and debugging.

July 26 – August 8 ( 2 Weeks)

Add Documentation export support for REST to wiki format.
Create WUI on the REST Module to enable export

August 9 – August 22( 2 Weeks)

Testing of WUI for newly adding REST Documentation supported
Inside-out tests, address robustness issues with modlues and improve performance of libraries.
Check code for memory leaks and performance analysis, with unit tests added for implemented modules.

August 23 – August 29( 2 weeks)

Pencils Down, Code clean up.
Review documentation and improvements to REST API
Final evaluation, Submission of code to melange.

Time Availability

I would be able to offer over 40 hours on the project. However, since the project would start during our second Semester; I would be coding mostly during the nights up to late June or early July when our semester ends. Also, to meet up with the demands of the project, I would be coding during weekends and regularly informing my mentors on the status of the project and regularly updating my logs in this respect.

Why OpenMRS?

I believe in OpenMRS' mission to impact the lives of people with better Health care services. I have felt the impact of OpenMRS efforts in improving the lives of Africans through better health care infrastructure. Looking at the fight OpenMRS put to fight Ebola which took the lives of my brothers and sisters, I believe I could be part of the solution by writing code for Africans by an African.

Why Me?

First of all hailing from Africa with lack of computing infrastructure posed a lot of great challenges to ascend to hackerdom especially with the scarcity of good programmers and lack of Internet access. Working with BRL-CAD in 2013 taught me a great deal especially working with the brightest researchers in this field. I believe my participation in GSoC this year would not only give me a great learning experience but also heighten my ambition of being a great Computer Science researcher in Africa. I see this project as both an intellectual challenge to gain both the respect of OpenMRS developers and also impact the lives of Africans across the continent.