Writing Documentation for language

We are trying to create a language which we think will change from time to time. If there is a Concept A and a property B, we need to write why such property is needed etc.

I mean like we document Java instance variables, I want to document every thing I am writing in MPS. It may be a Concept or Editor or Generator. For some strange reason, I am not able to find how to do it.

Does such functionality exist? How can I do it?
7 comments
Rajesh,

We are thinking about this functionality for a long time, but don't have time to implement it.
I would suggest looking on MPS "Annotations". This is how "Deprecated" annotation is implemented on a concept. The thing is that the concept doesn't know about annotations that can be attached to it. See "deprecatedNode" annotation link declaration for an example (can be found with ctrl-n).

In a couple words - the
  • deprecatedNode root states that we can add a special "child" of type "DeprecatedNodeAnnotation" to each node of type
  • IStructureDeprecatable is a marker interface for those concepts whose instances can be deprecated
  • DeprecatedNodeAnnotation defines the structure and editor of the annotation itself.

I've called other MPS developers to have a look at this thread and post their ideas.
If you have further questions, feel free to ask.
Mihail
0
Maybe the previous message is not very clear - I mean it is one f the possible solutions - to make an annotation for your documentation comments. Definitely, with another editor it can look as a documentation comment. It's just a way of adding new features to a language that you can't change.
0
Thank you for the reply. When I have seen Deprecated annotation, I thought the possibility of using similar stuff.
0
I had an idea to incorporate documentation to the editor cells somehow, to be able to press Ctrl+Q on the node in the edited model and see some pop-up with documentation. But have no idea how to implement that. There is action map/key map in the Inspector.. but what to do with that..
0
Igor,
The feature you've mentioned is better to be done within plugin aspect using Actions. You just add an action to editor popup menu and assign a shortcut to it (AFAIR, in 2.0 you can do it directly in action itself). In action, you just show the popup.
See ShowParameters action to find out how we've done it in a similar case (showing parameters of a method in a method call)&

Regards,
Mihail
0
Frankly speaking, I forgot how to work with MPS (besides creating concepts), did not use it for couple of years.
Now that it will be in IDEA, it's time to study it again.
Still, I'd like to put some "comments" to the concepts..and only then to show them. E.g. how to "comment" enum elements? No idea..
0
Talking briefly the idea of documentation language is:
  • it should be a separate language
  • it should be possible to attach documentation comment to any concept instances with some specific precondition (e.g. implementing marker interface)
  • it should be possible to type text in documentation comment (m.b. rich text)
  • it should be possible to put references from within this comment onto any other model elements in nearby models

As a starting point you can use jetbrains.mps.baseLanguage.javadoc language - currently existing language for documenting java.
0

Please sign in to leave a comment.