Skip to content

Indexing documentation

Camil Staps requested to merge 112-documentation into master

This partially resolves #112 (closed). There are also changes in the submodule Cloogle (and its submodule libcloogle). Minor changes to clean.js have been pushed to master directly.

This PR is not meant to be merged as-is, but serves as a discussion thread. Once agreed on, changes in several libraries have to be merged to master (which will mean updating the submodules here with the new commit hashes).

Currently supported:

  • Docblocks (/** ... */) before functions, macros and type definitions
  • Doclines (//* ...) after record fields and constructors

Not supported yet:

  • Docblocks before class members (scanning issue in the Clean compiler)
  • Module docblocks (to be done)
  • Doclines after functions and macros (need to be discussed if we want this; occasionally doclines appear before functions as well so this may give wrong results)
  • Record field documentation is a single string, so if the field has the type of a function, you cannot use @param. Record fields can only carry doclines, not docblocks. Same for constructors.
  • Class documentation is not shown yet on the frontend
  • Documentation fields like @param are limited to one line
  • Searching for documentation (need to be discussed if we want this and how)

Overview of the implementation:

  • Patches for the clean-compiler are added in the Cloogle submodule. This allows indexing of documentation. Documentation is parsed for fields like @param, @result, etc. and stored in types.json.
  • New fields have been added to the result fields in libcloogle, for a general description and the descriptions of parameters, results, record fields, etc.
  • On the frontend, a general description is shown in the metadata section of a result. Parameter and result descriptions goes under a more information link. Documentation for fields and constructors appears as comments (doclines) in the code result.

Screenshots:

2017-05-29-135505_727x93 2017-05-29-135514_724x182 2017-05-29-135530_643x151

Merge request reports