Still needs work
Deleted comment, after reading the docs over again, I misinterpreted them.
Currently, when build.gradle has some source folder like "../scripts" (e.g. as found in the build file for the grails-core project). This now gets turned into a linked resource, pointing to an absolute file system location.
This is not a nice solution because this absolute file system location will end-up in the project's .project file.
This file should typically be committed into source control (if not, Eclipse will get rather confused about the project when it is checked out from source control).
It is very undesirable to have absolute path references inside of files committed to source control since they are very specific to a given users setup and will likely not work for other users checking out the same project from source control.
Probably the mapping of these funny source folders onto something that works in Eclipse should, if possible try to use path variables in some fashion to keep the .project file free of absolute path names (unless the user's build script itself contains absolute references, in which case it is the users own choice/fault).
Makes perfect sense. To me it's a next logical step. Before the change the eclipse project didn't even import when source folder was 'external.
Right. I'll keep watching this issue for updates 
When we get to that point, we'd need to think a bit on what path variables will be defined and how. If the tooling API provides a method to query what variables it wishes to define, I suppose I could call appropriate API on my side to create them.
In the mean time, I've got something implemented that seems to work for the one case that I know this is used for (i.e. a source folder like '../<something>').
I have also implemented support for the case where the target is an IFile, but I have no test case for it. What kind of constructs should I put in a gradle project / build file to get something that has linked IFile resources?
I have not implemented anything yet to support the virtual folders case. Is this used by Gradle for anything (yet)? I don't think I'll implement support for it until I have a test project that exercises this functionality.
Also, unless I'm reading the JavaDocs in EclipseLinkedResource wrong (possible. For the case where getLocationURI is used(not null) the 'type' property doesn't discriminate between folders and files.
If that's true, then it is a bit problematic since the Eclipse API for creating linked resources requires you to create either a linked folder or a linked file. There is no 'generic' linked resource.
We may chop this issue into smaller pieces.
Gradle does not offer any way to configure virtual folders at the moment. I'm not very keen on supporting them soon because it feels they are used extremely rarely (not to mention that eclipse virtual folders are awkward - with all respect to Eclipse
Gradle is quite agnostic about what the users put in type field. It's up to the user to configure the linked resource and specify the type, location, etc. Theoretically, some users may have links that point to files. However, I would bet that no one really configures linked resources explicitly in his gradle build. The linked resources were fixed in one of the recent milestones. Gradle automatically only creates folder links when source folders are 'external' to project. So, I wouldn't worry too much about the file links.
The javadoc documentation for linked resource is based on the official Eclipse documentation and my tests. I found the documentation somewhat incorrect & incomplete. My questions are here: http://www.eclipse.org/forums/index.php/m/689469/?srch=linked+resources#msg_689469
So, you're reading the documentation correctly, if locationURI is used then the 'type' will not tell you if it is a folder or a file. That's how eclipse models it at this moment :/
I agree with you on Virtual folders. No reason to support this unless some user actually asks for it.
I was looking at the APIs to create linked resources, not the format of the .project file. Not quite sure how well these map onto eachother. It is a fact however that there's no way to create a linked resource through the API unless you know whether it points to a file or a folder. (Either you use methods of IFile or of IFolder...)
Interesting tidbit is that in the API, it does look like you can use the 'location' (as opposed to the 'locationURI') methods also with path variables. The determining factor seems to be that when the path is relative it is expected to start with a path variable.
See here:
Anyhow, I think we can leave it at what it is for now, but if we want to start making use of path variables, we'll need to dig a little deeper into the Eclipse internals.
Ok, I see.
I only documented/focused on the quirks of 'locationURI vs location' related to the persistent format of the .project. So it may be that location can use variables. However, it appears that in the .project you need to use locationURI for variable-driven path because otherwise it doesn't work correctly.
>if we want to start making use of path variables, we'll need to dig a little deeper into the Eclipse internals.
Yeah, possibly. Though, I think it should be feasible to 'tweak' the current eclipse plugin to generate 'variable relative' linked resources that may be more useful for you (e.g. toolingApi).
I'd like to close this issue to tidy up things before release. It feels that maintaing coarse-grained issues that span multiple releases is not a good idea. Kris/Adam, if you find some specific issues with linked resources feel free to create a focused jira ticket 
If someone disagrees please reopen!