Home » Modeling » EMF » Solved: [EMF] [XCore] Generating HTML JavaDoc from generator output
| Solved: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1441286] |
Thu, 09 October 2014 14:08  |
 Phillip Keldenich
Messages: 9
Registered: January 2014 |
Junior Member |
|
|
Hey,
I am looking for a clean way to produce actual HTML javadoc output for the generated source code from EMF/Xcore (preferrably only for the generated interfaces).
The problem here are the tags @generated, @model, @ordered, ... that are not part of the javadoc standard.
I can tell the javadoc tool to ignore these tags with the "-tag model:x" command line argument.
I do not really need them in the output, though a preferred solution would also include them in some useful form; perhaps some standard javadoc taglet for these tags or something similar would be nice.
However, sometimes the code generator splits the argument of the @model tag up into several lines like:
@model kind="operation" unique="false"
annotation="..."
where the annotation argument contains some malformed HTML with special <%...%> sequences in it.
When split up across several lines, the javadoc tool does not ignore the second line (it does not seem to consider it a part of the @model tag), so this ends up in the javadoc output.
Due to the fact that it is not correct HTML, this breaks the output documents and produces lots of error messages.
Are there any standard taglets for EMF-generated javadoc comments?
If yes, where can I find them? I tried to find some, but all I found was the Taglets collection which did not work for me (failed to load).
If no, how do you setup your javadoc to deal with this?
Btw, I am using the javadoc binary provided by a recent jdk1.8, but I could probably switch to a 1.7 one.
Regards,
Phillip
[Updated on: Tue, 14 October 2014 13:08] Report message to a moderator |
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1442226 is a reply to message #1441286] |
Fri, 10 October 2014 20:34  |
Ed Merks
Messages: 33133
Registered: July 2009 |
Senior Member |
|
|
Phillip,
Comments below.
On 09/10/2014 4:08 PM, Phillip Keldenich wrote:
> Hey,
>
> I am looking for a clean way to produce actual HTML javadoc output for
> the generated source code from EMF/Xcore (preferrably only for the
> generated interfaces).
>
> The problem here are the tags @generated, @model, @ordered, ... that
> are not part of the javadoc standard.
> I can tell the javadoc tool to ignore these tags with the "-tag
> model:x" command line argument.
> I do not really need them in the output, though a preferred solution
> would also include them in some useful form; perhaps some standard
> javadoc taglet for these tags or something similar would be nice.
I'm not sure what magic we do to generate docs that look like this:
http://download.eclipse.org/modeling/emf/emf/javadoc/2.10.0/org/eclipse/emf/ecore/EAnnotation.html
Presumably some extra doclet processing.
> However, sometimes the code generator splits the argument of the
> @model tag up into several lines like:
>
> @model kind="operation" unique="false"
> annotation="..."
>
> where the annotation argument contains some malformed HTML with
> special <%...%> sequences in it.
> When split up across several lines, the javadoc tool does not ignore
> the second line (it does not seem to consider it a part of the @model
> tag), so this ends up in the javadoc output.
> Due to the fact that it is not correct HTML, this breaks the output
> documents and produces lots of error messages.
I see; you're saying there are unescaped characters like < in it. That
sounds a bit like a bug...
>
> Are there any standard taglets for EMF-generated javadoc comments?
I'm really not sure how we process the Javadoc to produce ours. I'll ask
Dennis.
> If yes, where can I find them? I tried to find some, but all I found
> was the Taglets collection which did not work for me (failed to load).
> If no, how do you setup your javadoc to deal with this?
> Btw, I am using the javadoc binary provided by a recent jdk1.8, but I
> could probably switch to a 1.7 one.
Bad characters sounds like a bug though; I can see how that would happen
with given how imports are escaped with <%%>...
>
> Regards,
> Phillip
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1442533 is a reply to message #1441286] |
Sat, 11 October 2014 08:05 |
Phillip Keldenich
Messages: 9
Registered: January 2014 |
Junior Member |
|
|
The link you have posted looks somehow like what I would expect Javadoc to produce.
It seems like you have (somewhere) a definition for the custom tags that the code generator produces.
If you suspect that there is a bug somewhere, this is generated as part of the documentation (on the Interface, not one of the ...Impl classes):
/* [...]
* @model kind="operation" unique="false"
* annotation="http://www.eclipse.org/emf/2002/GenModel body='boolean _and = false;\nboolean _and_1 = false;\nboolean _and_2 = false;\nboolean _and_3 = false;\nboolean _and_4 = false;\n<%java.lang.Object%> _key = this.getKey();\nboolean _notEquals = (!<%com.google.common.base.Objects%>.equal(_key, null));\n [...]"
*/
It goes on like this; it seems to be the entire generated body of the method. There is no @GenModel(body=...) annotation on the method, but this seems to be restricted to those methods where I wrote some method body in XCore.
Also note that there is a newline behind the unique="false", which creates issues with the "-tag model:x" solution.
[Updated on: Sat, 11 October 2014 08:11] Report message to a moderator |
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1442583 is a reply to message #1442533] |
Sat, 11 October 2014 10:04 |
Ed Merks
Messages: 33133
Registered: July 2009 |
Senior Member |
|
|
Phillip,
Comments below.
On 11/10/2014 10:05 AM, Phillip Keldenich wrote:
> The link you have posted looks somehow like what I would expect
> Javadoc to produce.
:-)
> It seems like you have (somewhere) a definition for the custom tags
> that the code generator produces.
Yes, there must be some special processing going on...
>
> If you suspect that there is a bug somewhere, this is generated as
> part of the documentation (on the Interface, not one of the ...Impl
> classes):
> /* [...]
> * @model kind="operation" unique="false"
> * annotation="http://www.eclipse.org/emf/2002/GenModel
> body='boolean _and = false;\nboolean _and_1 = false;\nboolean _and_2 =
> false;\nboolean _and_3 = false;\nboolean _and_4 =
> false;\n<%java.lang.Object%> _key = this.getKey();\nboolean _notEquals
> = (!<%com.google.common.base.Objects%>.equal(_key, null));\n [...]"
> */
Well, it's expect to generate that. All implementations of this
interface will effectively "insert" that body and as part of that
processing the <%...%> is processed to produce an import (if possible)
and to use the imported name. Is it the <% that's causing a problem,
the fact that is spans multiple lines (which is normal for an @ tag,
..e.g, with @parameter one can do that...
>
> It goes on like this; it seems to be the entire generated body of the
> method. There is no @GenModel(body=...) annotation on the method, but
> this seems to be restricted to those methods where I wrote some method
> body in XCore.
Yes, that's expected, but I am concerned how that affects Javadoc
generation...
An example is
* @see org.eclipse.emf.ecore.EcorePackage#getEStructuralFeature()
* @model abstract="true"
* annotation="http://www.eclipse.org/emf/2002/Ecore
constraints='ValidDefaultValueLiteral'"
* @generated
*/
public interface EStructuralFeature extends ETypedElement
which generates
http://download.eclipse.org/modeling/emf/emf/javadoc/2.10.0/org/eclipse/emf/ecore/EStructuralFeature.html
which looks okay.
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1444641 is a reply to message #1442583] |
Tue, 14 October 2014 10:46 |
Phillip Keldenich
Messages: 9
Registered: January 2014 |
Junior Member |
|
|
Hello Ed,
I agree with you that it may be expected to produce something like that, and also that multiple line spanning tags may be okay in some circumstances, when there are special processing taglets/doclets? in place.
It just makes it much harder to use a javadoc generator without this rather sophisticated special processing (which is not publicly available, at least its not easy to find anywhere), because it is not easy (by means of command line arguments, ...) to tell javadoc to ignore these tags and that they may span multiple lines.
I think it should not be necessary to know how to write custom javadoc taglets/doclets and to write your own (probably fragile and error-prone, especially with version changes) taglets in order to use XCore/EMF and generate a javadoc documentation for your model (that works without tons of errors, warnings and a kindof broken output).
Could you (or anyone that is responsible for that) provide a taglet/doclet that handles these tags?
Regards,
Phillip
|
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1444706 is a reply to message #1444641] |
Tue, 14 October 2014 12:43 |
Ed Merks
Messages: 33133
Registered: July 2009 |
Senior Member |
|
|
Phillip,
Comments below.
On 14/10/2014 12:46 PM, Phillip Keldenich wrote:
> Hello Ed,
>
> I agree with you that it may be expected to produce something like
> that, and also that multiple line spanning tags may be okay in some
> circumstances, when there are special processing taglets/doclets? in
> place.
> It just makes it much harder to use a javadoc generator without this
> rather sophisticated special processing (which is not publicly
> available, at least its not easy to find anywhere),
Indeed.
> because it is not easy (by means of command line arguments, ...) to
> tell javadoc to ignore these tags and that they may span multiple lines.
I see.
> I think it should not be necessary to know how to write custom javadoc
> taglets/doclets and to write your own (probably fragile and
> error-prone, especially with version changes) taglets in order to use
> XCore/EMF and generate a javadoc documentation for your model (that
> works without tons of errors, warnings and a kindof broken output).
Indeed.
> Could you (or anyone that is responsible for that) provide a
> taglet/doclet that handles these tags?
The number of things people desire far exceeds my capacity to provide
them... I suppose setting "Suppress EMF Model Tags" won't make you
entirely happy, but it does avoid the whole issue too.
>
> Regards,
> Phillip
>
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1444714 is a reply to message #1444706] |
Tue, 14 October 2014 13:00 |
Phillip Keldenich
Messages: 9
Registered: January 2014 |
Junior Member |
|
|
I understand that, and for the time being, unless it breaks other things, I would be perfectly happy with the "Suppress EMF model tags" solution.
But how to I tell xcore to set this property?
I can't do that in the reflective editor/properties view (I cant seem to change anything in there), so I suppose it can be done by some @GenModel annotation, but I can not find what exactly to put in there, and where to put the annotation.
Edit: Ah, found it, a bit of trial and error, but the properties view is really helpful (when you open/use it) with the normal xcore editor open. This solves my problem.
[Updated on: Tue, 14 October 2014 13:07] Report message to a moderator |
|
|
| Re: [EMF] [XCore] Generating HTML JavaDoc from generator output [message #1444749 is a reply to message #1444714] |
Tue, 14 October 2014 13:51 |
Ed Merks
Messages: 33133
Registered: July 2009 |
Senior Member |
|
|
Phillip,
Comments below.
On 14/10/2014 3:00 PM, Phillip Keldenich wrote:
> I understand that, and for the time being, unless it breaks other
> things, I would be perfectly happy with the "Suppress EMF model tags"
> solution.
> But how to I tell xcore to set this property?
When you have a *.xcore open, the properties view shows the GenModel
properties associated with your selection. If you change something, it
modifies the source to record those changes as @GenModel annotations.
> I can't do that in the reflective editor/properties view (I cant seem
> to change anything in there), so I suppose it can be done by some
> @GenModel annotation, but I can not find what exactly to put in there,
> and where to put the annotation.
Ed Merks
Professional Support: https://www.macromodeling.com/
|
|
|
Goto Forum:
Current Time: Tue Apr 16 04:49:55 GMT 2024
Powered by FUDForum. Page generated in 0.16022 seconds |
] 
Search
Help
Register
Login
Home
