Eclipse Community Forums: TMF (Xtext) » How to generate API document of DSL?

Help

Home

Home » Modeling » TMF (Xtext) » How to generate API document of DSL?

Show: Today's Messages :: Show Polls :: Message Navigator

How to generate API document of DSL? [message #1779001]

Thu, 28 December 2017 07:26

serio adamo

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.

Report message to a moderator

Re: How to generate API document of DSL? [message #1779003 is a reply to message #1779001]

Thu, 28 December 2017 08:07

Christian Dietrich

Messages: 14665
Registered: July 2009

Senior Member

There is no such thing right now so you would need to build it yourself

Twitter : @chrdietrich
Blog : https://www.dietrich-it.de

Report message to a moderator

Re: How to generate API document of DSL? [message #1779004 is a reply to message #1779003]

Thu, 28 December 2017 08:34

Uli Merkel

Messages: 250
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))

Report message to a moderator

Re: How to generate API document of DSL? [message #1779006 is a reply to message #1779004]

Thu, 28 December 2017 08:52

serio adamo

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.

Report message to a moderator

Re: How to generate API document of DSL? [message #1779009 is a reply to message #1779006]

Thu, 28 December 2017 10:00

Ed Willink

Messages: 7655
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

Report message to a moderator

Re: How to generate API document of DSL? [message #1779011 is a reply to message #1779009]

Thu, 28 December 2017 10:42

serio adamo

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).

Report message to a moderator

Re: How to generate API document of DSL? [message #1779027 is a reply to message #1779011]

Fri, 29 December 2017 08:40

Uli Merkel

Messages: 250
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

Report message to a moderator

Re: How to generate API document of DSL? [message #1779777 is a reply to message #1779027]

Fri, 12 January 2018 13:07

Stéphane Galland

Messages: 123
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.

Report message to a moderator

Previous Topic:	Invalid resource link in BatckLinkableResourceStorageWritable
Next Topic:	cross-project references not resolved in standalone mode

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

]

Current Time: Thu Apr 25 09:24:23 GMT 2024

.:: Contact :: Home ::.

Breadcrumbs

Sign up to our Newsletter