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

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

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

Thu, 28 December 2017 02:26

Eclipse User

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 03:07

Eclipse User

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

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

Thu, 28 December 2017 03:34

Eclipse User

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 03:52

Eclipse User

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 05:00

Eclipse User

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 05:42

Eclipse User

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 03:40

Eclipse User

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 08:07

Eclipse User

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.

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

Goto Forum:

-=] Back to Top [=-

Current Time: Sun Jul 20 12:50:10 EDT 2025

.:: Contact :: Home ::.

Breadcrumbs

Sign up to our Newsletter