Bugzilla – Full Text Bug Listing
| Summary: | Updates needed to the Resources docs | ||
|---|---|---|---|
| Product: | [Eclipse Project] Platform | Reporter: | Szymon Brandys <Szymon.Brandys> |
| Component: | Doc | Assignee: | Serge Beauchamp <serge> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | john.arthorne |
| Version: | 3.6 | ||
| Target Milestone: | 3.6 | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| Whiteboard: | |||
|
Description
Szymon Brandys
Workbench User Guide > Getting Started > Basic Tutorial > Importing Files > Import Wizard - the screenshot should be updated. We should add the 'File and Folder Operation' dialog to Help. Maybe here Workbench User Guide > Getting Started > Basic Tutorial > Importing Files. Workbench User Guide > Tasks > Working with projects, folders and files - we could perhaps add a task that describes creating resource filters. Workbench User Guide > Reference > Preferences > Linked Resources - the screenshot should be updated. Workbench User Guide > Reference > User interface environment > Wizards > Import wizard > File system - the screenshot and option table should be updated. Platform Plug-in Developer Guide > Resources overview - Linked resources should be updated. We should add details about Virtual Folders and Resources Filters. Maybe all three concepts should be gathered within one section? Platform Plug-in Developer Guide > Advanced Resources concepts - we could add advanced details for Dynamic Path Variables and Resource Filters here. Things like ext. points. Platform Plug-in Developer Guide > Reference > Extension Points Reference - we should add descriptions of new ext. points here. Serge, any news on that? (In reply to comment #1) > Workbench User Guide > Getting Started > Basic Tutorial > Importing Files > > Import Wizard - the screenshot should be updated. > Done. > We should add the 'File and Folder Operation' dialog to Help. Maybe here > Workbench User Guide > Getting Started > Basic Tutorial > Importing Files. > Done - I added it to the 'Drag and drop of copy and paste' section, since it already discussed drag and drop. > Workbench User Guide > Tasks > Working with projects, folders and files - we > could perhaps add a task that describes creating resource filters. > Done. > Workbench User Guide > Reference > Preferences > Linked Resources - the > screenshot should be updated. > Done. > Workbench User Guide > Reference > User interface environment > Wizards > > Import wizard > File system - the screenshot and option table should be > updated. > Done. > Platform Plug-in Developer Guide > Resources overview - Linked resources should > be updated. We should add details about Virtual Folders and Resources Filters. > Maybe all three concepts should be gathered within one section? > I updated the 'Linked resources' section to discuss virtual folders, and added a new 'Resource Filters' section. > Platform Plug-in Developer Guide > Advanced Resources concepts - we could add > advanced details for Dynamic Path Variables and Resource Filters here. Things > like ext. points. > > Platform Plug-in Developer Guide > Reference > Extension Points Reference - we > should add descriptions of new ext. points here. Done Great work Serge! Marking fixed. (In reply to comment #3) > > Platform Plug-in Developer Guide > Resources overview - Linked resources > should > > be updated. We should add details about Virtual Folders and Resources Filters. > > Maybe all three concepts should be gathered within one section? > > > > I updated the 'Linked resources' section to discuss virtual folders, and added a > new 'Resource Filters' section. The fact that virtual folders are implemented on top of linked resources should not be exposed to users. This may change, so #isLink may return false for virtual folders in the next release. I would separate the linked resources section from the virtual folders section then. Or the section should be renamed to 'Linked resources and virtual folders'. This should be fixed for 3.6. The content of the resource filters and virtual folders sections is a good start. They are pretty limited comparing to the description of resource markers though. I would keep updating these sections, but this could perhaps wait till 3.7. (In reply to comment #5) > The fact that virtual folders are implemented on top of linked resources should > not be exposed to users. This may change, so #isLink may return false for > virtual folders in the next release. I would separate the linked resources > section from the virtual folders section then. Or the section should be renamed > to 'Linked resources and virtual folders'. This should be fixed for 3.6. > Hum, I agree that the implementation details of virtual folders shouldn't be exposed to the user, but to the client API, I think it's a different issue. Whether or not virtual folders return true for isLinked() I think should be part of the API contract, and not change once set. I think the reason why we choose to have virtual folders return true for isLink is for backward compatibility reasons, where some client code might have something like: if (resource.isLinked()) { if (resource.getLocation() != null) ... } So that since virtual folders are very similar to linked resource folders (in fact, are identical to a linked resource folder with an invalid location), we support legacy client API transparently by having virtual folders return true for isLinked(). But whether or not this decision holds, I think the most critical part is that once that contract is made, it won't change in the future. As such, as long as 3.6 is concerned, virtual folders return true for isLinked(), so are effectively linked resources from the API perspective, independently of their implementation (whether they are effectively stored as linked resources as they are now, or used to be stored as a separate entry in the project description in e4). What do you think? > The content of the resource filters and virtual folders sections is a good > start. They are pretty limited comparing to the description of resource markers > though. I would keep updating these sections, but this could perhaps wait till > 3.7. Sure. (In reply to comment #6) > (In reply to comment #5) > Hum, I agree that the implementation details of virtual folders shouldn't be > exposed to the user, but to the client API, I think it's a different issue. > > Whether or not virtual folders return true for isLinked() I think should be part > of the API contract, and not change once set. > > I think the reason why we choose to have virtual folders return true for isLink > is for backward compatibility reasons, where some client code might have > something like: I don't think we chose to return #isLink=true for virtual folders. It's just an implementation detail. I recall that it was discussed on another bug. See bug 300381, comment 2 and others. IResource#getLocation may return null for resources other than linked ones, so even if we return #isLinked=false later, this will be also backward compatible, right? > So that since virtual folders are very similar to linked resource folders (in > fact, are identical to a linked resource folder with an invalid location), we > support legacy client API transparently by having virtual folders return true > for isLinked(). > > But whether or not this decision holds, I think the most critical part is that > once that contract is made, it won't change in the future. That's why I would not do this contract now, to have more flexibility during 3.7. > As such, as long as 3.6 is concerned, virtual folders return true for > isLinked(), so are effectively linked resources from the API perspective, > independently of their implementation (whether they are effectively stored as > linked resources as they are now, or used to be stored as a separate entry in > the project description in e4). They are not linked resources, we just expose the implementation in #isLinked method. > > The content of the resource filters and virtual folders sections is a good > > start. They are pretty limited comparing to the description of resource > markers > > though. I would keep updating these sections, but this could perhaps wait till > > 3.7. > > Sure. Bug 315956 raised. (In reply to comment #7) > I don't think we chose to return #isLink=true for virtual folders. It's just an > implementation detail. > I recall that it was discussed on another bug. See bug 300381, comment 2 and > others. > Well, I remember the reasoning behind that, because it didn't used to to be the case in e4 ('groups' returned true for isGroup(), but not 'isLinked()'). Changing it in 3.6 (from e4) required changes in ui.ide as well, since it required changes in conditions tests such as "if (res.isLinked() && !res.isVirtual())" > IResource#getLocation may return null for resources other than linked ones, so > even if we return #isLinked=false later, > this will be also backward compatible, right? > Well, I think the only condition for which getLocation() would return null is if the workspace isn't in sync, right? but as long as it is, the client could, before, legitimately expect getLocation() never to be null except than for linked resources. > > once that contract is made, it won't change in the future. > > That's why I would not do this contract now, to have more flexibility during > 3.7. > Either way, if we change it, it will require changes in the client, since it will break the API contract. Right now, isLinked() == true for virtual folders, but if we make it so in 3.6 isLinked() == false for virtual folders, then change it to == true in the future, it will still break the API contract and require client changes. My perspective, is that we should have isLinked() == true for virtual folders, not because they are internally implemented the same way as linked resources, but because they share the same API contract as linked resources (can return null for getLocation(), the parent of the resource isn't the location of the workspace parent container, doesn't cause the underlying FS resource to be deleted unpon deletion, etc...). If it would return isLinked() == false, we'd have to pepper the client code with special isVirtual() code handling. IsLinked() == true is much more compatible. > They are not linked resources, we just expose the implementation in #isLinked > method. > Well, that's a matter of definition. What is a linked resource? Anything that isLinked() return true? Then yes, in that case, a virtual folder would be a special kind of linked resources, from the API perspective. Or anything that shares the property of a linked resource? Then a virtual folder is identical in terms of property with a linked resource folder with an invalid location, at one exception, setting its location to a valid doesn't make it valid. I would like to continue the discussion during 3.7. For now I would suggest to change the doc as I suggested in comment 5. (In reply to comment #9) > I would like to continue the discussion during 3.7. For now I would suggest to > change the doc as I suggested in comment 5. Fair enough, I now committed changes on head that creates a separate documentation entry for virtual folders, and de-emphasize that they are linked resources (only mentioning that isLinked() returns true). |