Automatic production of end user documentation for DSLs. (December 2018)

• Record Type: Journal Article
• Authors: Le Moulec, Gwendal; Blouin, Arnaud; Gouranton, Valérie; Arnaldi, Bruno
• Is Part Of: Computer languages, systems & structures. Volume 54(2018)
• Page Start: 337
• Page End: 357
• Publication Date: 2018-12
• Subjects: Software documentation -- Domain-specific language -- Model slicing; Programming languages (Electronic computers) -- Periodicals; Computer networks -- Periodicals; Computer architecture -- Periodicals; Computer systems -- Periodicals; Langage de programmation; Réseau d'ordinateurs; Architecture d'ordinateur; Périodique électronique (Descripteur de forme); Ressource Internet (Descripteur de forme); 005.13
• DOI: 10.1016/j.cl.2018.07.006
• Languages: English
• ISSNs: 1477-8424

Abstract

Highlights: This paper describes a model-driven approach that allows the automatic production of end user documentations that explain and illustrate the different concepts of a Domain-Specific Language (DSL). The approach produces end user documentation from artifacts of the implementation phase of DSLs: the metamodel, the grammar, and models that cover all the concepts of a DSL. Our implementation, called Docywood, targets two platforms: Markdown documentations for static web sites and Xtext code fragments for live documentation while modeling. The evaluation exhibits that the proposed approach improves the correctness of ThingML models created by novice end users. Abstract: Domain-specific languages (DSL) are developed for answering specific problems by leveraging the expertise of domain stakeholders. The development of DSLs requires a significant software engineering effort: editors, code generators, etc, must be developed to make a DSL usable. Documenting a DSL is also a major and time-consuming task required to promote it and address its learning curve. Recent research work in software language engineering focus on easing the development of DSLs. This work focuses on easing the production of documentation of textual DSLs. The API documentation domain identified challenges we adapted to DSL documentation. Based on these challenges we propose a model-driven approach that relies on DSL artifacts to extract information required to build documentation. Our implementation, called Docywood, targets two platforms: Markdown documentation for static web sites and Xtext code fragments for live documentation while modeling. We used Docywood on two DSLs, namely ThingML and Target Platform Definition . Feedback from end users and language designers exhibits qualitative benefits of the proposal with regard to the DSL documentation challenges. End user experiments conducted on ThingML and Target Platform Definition show benefits on the correctness of the created models when using Docywood on ThingML .