Create a function which makes a relation between types and functions.

The problem:

Technical documentation is not a luxury, but it is a necessity. Haskell has a powerful documentation generator called Haddock which renders comments in the source code as texts. However, the texts are only a way to present documentation. According a study*, supplementing text-based learning materials with diagrams helps students to recall the presented information. Diagrams project, provides a hackage called haddock-diagrams which allows to embed diagrams into the documentation generated by Haddock. However these diagrams have to be written by hand. Since, Haskell modules share the structure between its declared signatures, data types and classes, we can generate a diagram which represents this relation. So, this is the proposal of this project: write a module which will allow Haddock to generate a diagram which relates data types and functions using the GHC API, Diagrams Project and Haddock. In simple words, this diagram is helpful when the developer wants to know which function(s) receive(s) a FooT type and returns a BarT type.

The diagram will be generated from a ‘list of functions’ and from a ‘list of data types’. The output will be a graph whose nodes are the data types and type classes and whose edges describes two possible relationships between its nodes: a relation through a function or the relation of “inheritance” from a class. A diagram is worth a thousand words:

In the figure,

- ⊂ (edge): means an “inheritance” relationship. The FooT type ‘inheritage’ from BarT

- λ (edge): means a relationship through a function. Its behavior is described in the signature of λ

This is a simple example in which we draw a diagram given as parameters a ‘list of types’ (Num, Integer, Ord, Bool, String) and a list of functions (map, fromInteger, +, <=, >).

Goals and milestones:

1. Design the structure for the graph. Let’s call it ‘DocGraph’. (Less than a week)

It is just the creation of the necessary type which will represent the graph.

2. Create a function which returns the graph given a ‘list of functions’, a ‘list of modules’ and a ‘list of functions’. (2 weeks)

GHC API provides a module called HsCTypes which we could use in order tools like the ModuleGraph and the ModuleIface which give us information about a declarations in a module. This information will be used in order to generate the ‘DocGraph’.

3. Create a function similar to the function in (2) but not receiving the ‘list of modules’. It will look-up for modules loaded in the scope. (2 weeks)

The function will look at the scope in order to get the modules and to pass them to the function defined in (2).

4. Get Diagrams supporting adding links to text in SVG format, so we could navigate between diagrams. (1 week)

5. Create a function which allows to render a DocGraph as diagram using whichever preprocessor. (3 weeks)

This function uses ‘diagrams’ to generate the project. It will take a ‘DocGraph’ as parameter and will render its graphical representation. In the case of SVG each text which represents a data type, or each text which describes the name of a function should be linked to another page. I n the usecase of this proposal, it would be a link to a Haddock html file (the idea is that the user can navigate bewtween haddock HTML files trough the diagrams

6. Integrate the function (5) with Haddock. (4 weeks)

It means to add an option to Haddock executable to autogenerate documentation with embedded diagrams. Haddock files are a bunch of InstalledInterface. Each data type holds information about certain module. Thus if we access to these InstalledInterface we can obtain the module being able to pass this module to the function mentioned in (1).

About me:

My name is Fabián Orccón. I am a student in the PUCP University in Perú. Since I was very young (14 years-old) I was very passionate about Free Software. I’ve participated in a GSoC before (2014) with GNOME in the project Pitivi in a project to generate videos from a sequence of images. My first contact with Haskell was when I was with a friend who was making her thesis about Haskell. But I really got more into Haskell, when I studied it as part of a course in the university. Now I am more involved in the community.

github: http://github.com/cfoch

• https://github.com/cfoch/cabal
• https://github.com/cfoch/HaskellSamples
  

blog: http://cfoch-dev.tumblr.com

* http://www.ncbi.nlm.nih.gov/pubmed/24874510