Home » Modeling » TMF (Xtext) » Comments missing in code makes it hard to develop(Cannot easily find what pieces of the code do, and therefore track back design rationale)
| Comments missing in code makes it hard to develop [message #988791] |
Mon, 03 December 2012 08:38  |
 Joost van Pinxten
Messages: 51
Registered: November 2012 |
Member |
|
|
First off, Xtext is an awesome tool that allowed me to build a language in mere days; hardest part was getting the precedency and left-factoring for expressions right. The pointers that are provided in the documentation and several blogs are excellent. The default behavior will suffice in many cases.
Now that I have moved somewhat into more language-specific scoping and validation I find that the topic of scoping is at best cumbersome for a beginner. I think I do have a good notion of what should be provided by the scoping and what should be provided by the validation. However, the way the code is organized, does not make it easy to step into. The injection of several managers etc. don't make it easier, but this can be overcome by creating some sort of overview of wat can be used to get a specific type.
Eventually, I wound up trying to create some cross-referencing among imported modules. And I got into weird errors, as I wasn't using the code as it was supposed to. Searching through the Xtext code, in order to see how to use namespace/uri-imports in my custom scoping rule, I found that there is no functional documentation (which reflects the state of the API documentation obviously).
Not being able to grasp all the specific details of the functions, it all becomes a clutter to me and it would have greatly helped if there was some sort of a description of the goal of the functions. I.e. (i'm guessing this):
protected IScope createContainerScopeWithContext(Resource eResource, IScope parent, IContainer container,
Predicate<IEObjectDescription> filter, EClass type, boolean ignoreCase) {
if (eResource != null) {
URI uriToFilter = eResource.getURI();
if (container.hasResourceDescription(uriToFilter))
container = new FilterUriContainer(uriToFilter, container);
}
return createContainerScope(parent, container, filter, type, ignoreCase);
}
I think this function in DefaultGlobalScopeProvider is used to filter out unwanted eResources, but it's hardly trivial for me to deduce.
A function like getVisibleContainers could really use a description which states in plain English what the idea is, i.e. what containers should be visible.
I think this really puts a damper on the development of a mature Xtext-enabled environment; it would also probably mean that you have to spend less time explaining something for 'simple' questions, as I see regularly here on the forum.
Just my 2 cents, I can understand that it takes time to write excellent documentation, but it baffles me that even basic documentation is missing from the classes and methods.
[Updated on: Mon, 03 December 2012 08:41] Report message to a moderator |
|
|
| Re: Comments missing in code makes it hard to develop [message #988808 is a reply to message #988791] |
Mon, 03 December 2012 09:58  |
Sebastian Zarnekow
Messages: 3118
Registered: July 2009 |
Senior Member |
|
|
Hi Joost,
thanks for your feedback. The documentation is by far not optimal.
However, the JavaDoc of #getVisibleContainers states
/**
* @return a sorted list of all {@link IContainer}, which are visible
from the given {@link IResourceDescription}.
* In an Java environment this would correspond to the list of
class-path entries. The list includes the
* container that contains the given resource description. However, the
result may be empty due to
* internal errors.
*/
What else would you expect?
FilterURIContainer's doc desribes the class as
/**
* A container that virtually removes a {@link IResourceDescription
resource description}
* with a given {@link URI uri} from another container.
*/
Do you have a suggestion on how to improve on that?
Regards,
Sebastian
--
Looking for professional support for Xtext, Xtend or Eclipse Modeling?
Go visit: http://xtext.itemis.com
Am 03.12.12 09:39, schrieb Joost van Pinxten:
> First off, Xtext is an awesome tool that allowed me to build a language
> in mere days; hardest part was getting the precedency and left-factoring
> for expressions right. The pointers that are provided in the
> documentation and several blogs are excellent.
>
> Now that I have moved somewhat into scoping and validation I find that
> the topic is at best cumbersome for a beginner. I think I do have a good
> notion of what should be provided by the scoping and what should be
> provided by the validation. However, the way the code is organized, does
> not make it easy to step into. The injection of several managers etc.
> don't make it easier, but this can be overcome by creating some sort of
> overview of wat can be used to get a specific type.
>
> Eventually, I wound up trying to create some cross-referencing among
> imported modules. And I got into weird errors, as I wasn't using the
> code as it was supposed to. Searching through the Xtext code, in order
> to see how to use namespace/uri-imports in my custom scoping rule, I
> found that there is no functional documentation (which reflects the
> state of the API documentation obviously).
>
> Not being able to grasp all the specific details of the functions, it
> all becomes a clutter to me and it would have greatly helped if there
> was some sort of a description of the goal of the functions. I.e. (i'm
> guessing this):
>
> protected IScope createContainerScopeWithContext(Resource
> eResource, IScope parent, IContainer container,
> Predicate<IEObjectDescription> filter, EClass type, boolean
> ignoreCase) {
> if (eResource != null) {
> URI uriToFilter = eResource.getURI();
> if (container.hasResourceDescription(uriToFilter))
> container = new FilterUriContainer(uriToFilter,
> container);
> }
> return createContainerScope(parent, container, filter, type,
> ignoreCase);
> }
> I think this function in DefaultGlobalScopeProvider is used to filter
> out unwanted eResources, but it's hardly trivial for me to deduce.
>
> A function like getVisibleContainers could really use a description
> which states in plain English what the idea is, i.e. what containers
> should be visible.
>
> I think this really puts a damper on the development of a mature
> Xtext-enabled environment; it would also probably mean that you have to
> spend less time explaining something for 'simple' questions, as I see
> regularly here on the forum.
>
> Just my 2 cents, I can understand that it takes time to write excellent
> documentation, but it baffles me that even basic documentation is
> missing from the classes and methods.
|
|
|
| Re: Comments missing in code makes it hard to develop [message #988846 is a reply to message #988808] |
Mon, 03 December 2012 12:57 |
Joost van Pinxten
Messages: 51
Registered: November 2012 |
Member |
|
|
Hi Sebastian,
I should have been clearer, I understand the base implementations, and they are documented, as you show. However, e.g. DefaultGlobalScopeProvider ImportUriGlobalScopeProvider, ImportedNamespaceAwareLocalScopeProvider have an implied functionality (with an overridden getVisibleContainers), which I can only base on their name and a very small piece of information in the documentation. The code here extends the base case, but as far as I can find, there is nothing mentioned about the design. So I am forced to look into code which I am unfamiliar with.
To provide my own global scope provider, I want to be able to filter specific classes from the imported uri's or namespaces, but to implement this, I first need to dig in example code, as it is not obvious as how to implement this.
Also, it is mentioned on the forum that e.g. it should not happen that in the scoping an object still needs to be resolved; this must be done in the linking phase I believe. This kind of design rationale is also not documented and the code itself will simply allow this kind of 'bad decision' to be made (it's not forcing you, which I see as mostly a good thing, as this keeps it flexible).
From the Itemis blog: "It has been said that the documentation on that topic (scoping in particular) is good... once you have understood the topic." I am unsure that this is still the case, but it might just be that I've not been enlightened yet. The topic of scoping itself is not complicated for me, as I have a clear view what needs to happen where, but the implementational aspects seem to be haunting me.
Regards,
Joost
|
|
|
Goto Forum:
Current Time: Sat Apr 20 01:13:36 GMT 2024
Powered by FUDForum. Page generated in 0.03105 seconds |
] 
Search
Help
Register
Login
Home
