Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Modeling » TMF (Xtext) » How to generate API document of DSL?
How to generate API document of DSL? [message #1779001] Thu, 28 December 2017 07:26 Go to next message
serio adamo is currently offline serio adamoFriend
Messages: 24
Registered: September 2017
Junior Member
xtext can easily create DSL, but how to create API document of DSL?
For example:
I created a DSL by xtext and write some library using this DSL. Then I want to publish my library, but how to generate API documentation for this library?

If I use some general programming language to write my library, there are many tools which can generate API document automatically. (eg: sandcastle, doxygen, ...)

So, is there any tools which can generate API document automatically?
Ideally, it can scan DSL source code and generate API document from DSL interface and comments automatically. The document generated is a form of html or chm, and suport symbol search.
Re: How to generate API document of DSL? [message #1779003 is a reply to message #1779001] Thu, 28 December 2017 08:07 Go to previous messageGo to next message
Christian Dietrich is currently offline Christian DietrichFriend
Messages: 11900
Registered: July 2009
Senior Member
There is no such thing right now so you would need to build it yourself

Need professional support for Xtext, Xpand, EMF?
Go to: http://xtext.itemis.com
Twitter : @chrdietrich
Blog : christiandietrich.wordpress.com
Re: How to generate API document of DSL? [message #1779004 is a reply to message #1779003] Thu, 28 December 2017 08:34 Go to previous messageGo to next message
Uli Merkel is currently offline Uli MerkelFriend
Messages: 231
Registered: June 2013
Senior Member
Hi Serio,

assume that you have already a generator to create the sourcecode.
So what about to add another pass through the AST to generate the API for this sourcecode with

var String scriptFileName = resource.getURI().lastSegment.toString();
var String outFileBase = scriptFileName.substring(0,scriptFileName.lastIndexOf("."));
fsa.generateFile( outFileBase + '.DOCU',
makeTheDocu(resource, resource.contents.head as Model))
fsa.generateFile( outFileBase + '.CODE',
makeTheCode(resource, resource.contents.head as Model))
Re: How to generate API document of DSL? [message #1779006 is a reply to message #1779004] Thu, 28 December 2017 08:52 Go to previous messageGo to next message
serio adamo is currently offline serio adamoFriend
Messages: 24
Registered: September 2017
Junior Member
Uli Merkel wrote on Thu, 28 December 2017 08:34
Hi Serio,

assume that you have already a generator to create the sourcecode.
So what about to add another pass through the AST to generate the API for this sourcecode with


I can pass through the AST to generate some text (eg: extracting function name, params, comments,...), the text maybe a html.

But how to create high quality API documentation from these information?
Because I am not very familiar with HTML and CSS.

Ideally, I wish I only need to generate a xml/json/markdown which represent a document structure, some tool can read this file and generate beautiful API documentation automatically. The generated document can support symbol search and navigation.
Re: How to generate API document of DSL? [message #1779009 is a reply to message #1779006] Thu, 28 December 2017 10:00 Go to previous messageGo to next message
Ed Willink is currently offline Ed WillinkFriend
Messages: 5839
Registered: July 2009
Senior Member
Hi

If you have simple layout requirements you can autogenerate a *.textile or equivalent. You can re-use the Mylyn Wikitext/DocBook support to render in a variety of formats.

If you really want quality documentation then autogenerate Latex.

Regards

Ed Willink
Re: How to generate API document of DSL? [message #1779011 is a reply to message #1779009] Thu, 28 December 2017 10:42 Go to previous messageGo to next message
serio adamo is currently offline serio adamoFriend
Messages: 24
Registered: September 2017
Junior Member
Ed Willink wrote on Thu, 28 December 2017 10:00
Hi

If you have simple layout requirements you can autogenerate a *.textile or equivalent. You can re-use the Mylyn Wikitext/DocBook support to render in a variety of formats.

If you really want quality documentation then autogenerate Latex.

Regards

Ed Willink



What you said is how to generate from scratch.
But what I really want is template.
For example, in MSDN we found in System Namespace types is classified to following categories: "Class Structures Interfaces Delegates and Enumerations". But If I have more categories in my DSL?
Can I generate document like MSDN, but not hack their tools (eg: sandcastle).
Re: How to generate API document of DSL? [message #1779027 is a reply to message #1779011] Fri, 29 December 2017 08:40 Go to previous messageGo to next message
Uli Merkel is currently offline Uli MerkelFriend
Messages: 231
Registered: June 2013
Senior Member
Hi Serio,

perhaps you want to have a look what is possible with MARKDOWN (*.md)

This introduction may help you. https://hackernoon.com/boost-your-productivity-using-markdown-b8a84fc2a089
It demonstrates even how to specify flowcharts in just a couple of text lines (very impressing)

Happy new year to all of us XTEXT users/lovers/developers/committers/supporters,
Uli Merkel
Re: How to generate API document of DSL? [message #1779777 is a reply to message #1779027] Fri, 12 January 2018 13:07 Go to previous message
Stephane Galland is currently offline Stephane GallandFriend
Messages: 117
Registered: July 2014
Location: Belfort, France
Senior Member
Dear all.

Assuming that your DSL uses a documentation syntax that is compliant with Javadoc, you could take a look on my solution.

I have created a Javadoc doclet that may be used by Javadoc and enables to generate the API documentation. It uses my DSL syntax in place of the standard Java syntax in all the generated pages.

Github link: https://github.com/sarl/sarl/tree/master/docs/io.sarl.docs.doclet/src/main/java/io/sarl/docs/doclet

All the best.
Stéphane.


Dr.habil Stéphane Galland.
Belfort-Montbéliard University of Technologie, France.

http://www.multiagent.fr/People:Galland_stephane
http://www.sarl.io
http://www.arakhne.org
Previous Topic:Invalid resource link in BatckLinkableResourceStorageWritable
Next Topic:cross-project references not resolved in standalone mode
Goto Forum:
  


Current Time: Tue Apr 24 23:24:49 GMT 2018

Powered by FUDForum. Page generated in 0.02519 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software