Skip to content

Language Reference Generation (WollokDoc)

Jump to bottom
Fernando Dodino edited this page Aug 17, 2018 · 15 revisions

Based on wollokdoc comments near every class, wko, mixin, constructor and method definitions, we can generate our "Complete Language Reference Guide".

How to generate html files

Using the Development Environment, you have to launch WollokDocParser in package org.uqbar.project.wollok.wollokDoc, in org.uqbar.project.wollok.launch project.

image

You must set two configurations:

  • input folder: generally pointing to org.uqbar.project.wollok.lib project, src/wollok folder. This configuration has no preffix, you just set it.
  • output folder: ideally you should clone wollok site, get a local copy and point to that folder. In my case I'm using "home/fernando/workspace/wollok-doc/wollok-site/wollokdoc" (be careful, last segment is wollokdoc all lowercase). If your wollok-site folder is in "~/wollok-site", you must configure your output directory to "~/wollok-site/wollokdoc". This configuration must be set using -folder preffix.

image

There is a Generate WollokDoc.launch file in org.uqbar.project.wollok.launch project, so you should already have this launcher in Run Configurations of your Eclipse

When you launch generation, the output folder should have this structure:

+  {root wollok-site folder}
 + wollokdoc <== {this must be your root output folder, all lowercase}
   +- index.html 
   +- lang.html
   +- vm.html
   +- lib.html
   +- etc.
 + js subfolder

You must not delete js subfolders, otherwise navigation will be broken.

Then, you can start jekyll server and test it:

$ cd {root wollok site}  # do not use wollokdoc folder, but root instead
$ jekyll s -i

How it is implemented

wollokdocgenerator 1

WollokDocParser solves the main requirement, it has several methods for describing every class, wko, mixin, method and constructor. Main algorithm is describe here:

  • DirExplorer receives input folder and filters .wlk files, according to WollokDocParser.filterWollokElements() closure
  • Then, every .wlk file is parsed without validation (since by now game wko's begin with uppercase). There is a new method in WollokChecker for that.
  • Finally, each parsed WFile is transformed to html file.
  • What about WollokDocs? MultiLineCommentDocumentationProvider can obtain previous multiline comments from any EObject (WClass, WNamedObject, WMixin, WMethodDeclaration, WConstructor, etc.)
Clone this wiki locally