Enhancing RUSTDOC to Allow Search by Types

Mihnea DOBRESCU-BALAUR, Lorina NEGREANU
University POLITEHNICA of Bucharest,
313, Splaiul Independentei, Bucharest, 060042, Romania
mihnea@linux.com; lorina.negreanu@cs.pub.ro

Abstract: Programming languages have benefited from increased attention lately. With corporations like Google, Facebook and Mozilla investing in language design, there is a lot of activity in the mainstream languages domain. State of the art features like advanced type systems that were only available to more research-centered languages such as Haskell, are now making their way into the mainstream through languages like Rust. Rust is an up-and-coming system programming language that aims to fill the same role as C and C++, but in a much safer way. To achieve this, it brings a rich type system, alongside a pragmatic implementation of region based memory management, a feature that allows safe memory handling without the need of a garbage collector. Aiming for the mainstream, Rust comes with tooling to aid developers in their work. One such tool is Rustdoc, a program that automatically generates documentation based on type information and programmer comments. We aim to enhance Rustdoc to provide more advanced search support through features that are impossible to implement for dynamic languages, and even static languages with less advanced type systems, like C and Go.

Keywords: Documentation generators, search, type system, Rust.

>Full text
CITE THIS PAPER AS:
Mihnea DOBRESCU-BALAUR, Lorina NEGREANU, Enhancing RUSTDOC to Allow Search by Types, Studies in Informatics and Control, ISSN 1220-1766, vol. 24 (2), pp. 221-228, 2015. https://doi.org/10.24846/v24i2y201510

Introduction

Progress in type inference algorithms [4] has led to statically typed languages that are easier to use and more appealing to programmers. Thanks to their performance compared to dynamic languages, programming languages such as Scala, Go and Hack (Facebook’s version of typed PHP) are increasingly gaining popularity. Besides the mentioned ease of use and good performance, all these languages also come with great tooling.

While not specifically part of the language, accompanying tools are critical to a programming language’s success. They represent the ways in which a programmer interacts with the code. For example, any language should have (or support) a good debugger to make finding bugs easier. Also, it should have an easy to use package management and build system. Many programmers find the XML configuration files of Java package systems cumbersome. To overcome this, Scala brings a simpler format for specifying dependencies.

Another important tool is the documentation generator. Good languages are used in large projects, and large projects need great documentation. Having a standard way of generating documentation pages is key to effortless knowledge sharing. Java has Javadoc, Scala has Scaladoc and Go has Godoc. They all do a good job of generating formatted, Web-accessible documentation from source code. However, they share a key shortcoming – they only support searching symbols by name. Search by name covers one aspect of programming – the situation where the programmer encounters a function and wants to know what it does. But there is also the case when the programmer needs to find a function that does a particular operation, and because of various reasons (new language, new naming standards, new codebase etc.) the name of that function is unknown. In this situation, the ability to search by type would be perfect.

An important benefit of static typing, besides allowing for compile-time checking, is that the types act as documentation. So why shouldn’t the documentation generators use this information?

Our project aims to add this exact functionality to Rustdoc – the documentation generator of the up-and-coming (currently in alpha) Rust [14] programming language. Rust has a rich type system, similar to that of Haskell and ML, which allows representing complex information through the type annotations. Because of this, we consider it a great target language for searching documentation by types.

The rest of this article is structured as follows: first, we will introduce Rust, its features and look at an existing implementation of searching documentation by type for Haskell. Then, we will discuss our implementation for Rustdoc. Following this, we will examine the usage as well as the performance of our solution. Finally, we will present our conclusions as well as possible future work for the project.

REFERENCES

BOYAPATI, C., R. LEE, M. RINARD, Ownership Types for Safe Programming: Preventing Data Races and Deadlocks, in Proceedings of the 17th ACM SIGPLAN Conference on Object-oriented Programming, Systems, Languages, and Applications, ser. OOPSLA ’02, (New York, USA, 2002), pp. 211-230.
EDELSON, D., I. POHL, Smart Pointers: They’re Smart, But They’re Not Pointers, Citeseer, 1992.
GROSSMAN, D., D. MORRISET, T. JIM, M. W. HICKS, Y. WANG and J. CHENEY, Region-based Memory Management in Cyclone, in PLDI, J. Knoop and L. J. Hendren, (ed.) ACM, 2002, pp. 282-293.
JONES, S. P., D. VYTINIOTIS, S. WEIRICH, M. SHIELDS, Practical Type Inference for Arbitrary-rank Types, Journal of functional programming, vol. 17, no. 01, 2007, pp. 1-82.
JOUNNAUD, J.-P. and M. OKADA, Abstract Data Type Systems, Theoretical Computer Science, vol. 173, no. 2, 1997, pp. 349-391.
Javascript Object Notation, http://www.json.org (ac. 26th March 2015).
LEVENSHTEIN, V. I., Binary Codes Capable of Correcting Deletions, Insertions, and Reversals, Soviet physics doklady, vol. 10, no. 8, 1966, pp. 707-710.
LISKOV, B., S. ZILLES, Programming with Abstract Data Types, in Proceedings of the ACM SIGPLAN Symposium on Very High Level Languages, New York, NY, USA: ACM, 1974, pp. 50-59.
MITCHELL, N., Hoogle Overview, The Monad. Reader, vol. 12, 2008, pp. 27-35
Performance webapi, https://developer.mozilla.org/en-US/docs/Web/API/Performance/now (accessed 26th March 2015).
SOZEAU, M. and N. OURY, First-class Type Classes, in Theorem Proving in Higher Order Logics, Springer, 2008, pp. 278-293.
STROUSTRUP, B., Exception Safety: Concepts and Techniques, in A. Romanovsky, C. Dony, J. Knudsen, and A. Tripathi, (ed.), Advances in Exception Handling Techniques, ser. Lecture Notes in Computer Science, Springer Berlin Heidelberg, vol. 2022, 2001, pp. 60-76.
The Haskell Programming Language, https://www.haskell.org/ (accessed 26th March 2015)
The Rust Programming Language, https://www.rust-lang.org/ (accessed 26th March 2015)