Community
Participate
Working Groups
There's no JavaDoc provided with the Mylyn documentation, unlike a lot of the other Eclipse plugins. In fact, the documentation as a whole is pretty slim; it's very difficult to see how you c an use it to create your own connector without having to check mylyn out from the source repository.
Yes, we have been encouraging integrators and contributors to check Mylyn out into their workspace (http://wiki.eclipse.org/index.php/Mylyn_Contributor_Reference#Setup ) because this provides them all of Eclipse's code navigation facilities in addition to Javadocs, and also makes it easier for them to submit patches when they need something improved more quickly than we can get it to them. I other words, we are considering Eclipse do be a replacement for the web browser as a tool for browsing Javadoc ;) But is there a particular use case that you want the Javadocs themselves for? Regarding the general slimness of the documentation, we prioritized bugs and API improvements for 2.0 over docs (as characteristically usual) but are trying to improve on this in the 3.0 cycle (e.g. bug 195450).
Three ways; 1) Not everyone can get access to the CVS repository. I, for one, am behind a firewall at work and unable to access anything other than HTTP. Because of this decision, I was taking to (painfully) stepping through files in viewcvs to find out what to do. 2) Learning how the big picture works, or to create your own. I don't necessarily want to have the code checked out to find out what's going on when I can read about it. There's such limited documentation on e.g. creating your own connector, it would be useful to be able to derive a big picture from how all the classes fit together. 3) Not everyone who needs documentation is interested in seeing the Mylyn source code. Whilst having the source might encourage people to do so, you shouldn't be expecting to force people to have to use it to extend Mylyn. Not only that, but many other of the Eclipse projects have a standardised format/location for the references and the help server provides search for the same. I regularly go to http://help.eclipse.org/ for searching for JavaDoc, especially if I don't have the project imported. Indeed, you can configure the JavaDoc view with just an API over HTTP, which will also supply the JavaDoc filters and parameter names (instead of 'arg0') in the code. In summary; Source might be better than JavaDoc for some purposes, but that doesn't mean JavaDoc shouldn't be available too. (By the way, totally agree about getting the code right over the documentation, but the JavaDoc is a free one)
Alex, nothing is actually free and it is a huge work to keep JavaDoc in sync with the code.
Some JavaDoc is still more useful than no JavaDoc.
Sure. However if it would be my call to choose between writing JavaDocs, apply patch that waiting for a few weeks or fix some bugs - I would go for a fix. Another aspect is that it is unclear which part of the API is more important and only one who need that JavaDoc could tell. So, maybe the most lightweight option would be to ask question about how certain API works, so someone who respond to that could answer it and perhaps fill in the JavaDoc with the answer. Though that won't work too well for this project giving the current structure of the code ownership.
I don't necessarily think that you need to JavaDoc everything; and in any case, a JavaDoc shouldn't explain how a method works, it should explain the intent. Even one-liners in each class would be a step up; it's not clear what a TaskListFactory is, for example. Anyway, the cost of having no JavaDoc is that you make it much more difficult for others to (a) learn about what's going on, and (b) interest them to help. In comparison, the ECF codebase is well documented, has help specifically aimed at developers, as well as JavaDoc (http://help.eclipse.org/help33/topic/org.eclipse.ecf.doc/html/reference/ecfJavaDoc.html) bundled with it. I suspect that both ECF and Mylyn are 'niche' in comparison to the rest of the Eclipse codebase, but the difference between the two projects with regards to documentation is hugely noticeable. As for the 'important ones', I would say that classes in the non-internal packages and interfaces should be the top priority, followed by some of the AbstractXxxxXxx classes that people are expected to implement when providing a new repository/provider/whatever. Other internal classes are probably of little relevance. In addition, I'd value class JavaDoc the most useful of them all; even if it's just a one liner on some of the less important ones, since those are the things that give you the big picture. Then, public methods and public constants are probably the next two. Note that if you've got JavaDoc for an interface which an AbstractXxx implements, you effectively get the documentation for free in the second place. Ditto for subclasses of those AbstractXxx classes. A little info can go a long way.
(In reply to comment #6) > I don't necessarily think that you need to JavaDoc everything; and in any case, > a JavaDoc shouldn't explain how a method works, it should explain the intent. > Even one-liners in each class would be a step up; it's not clear what a > TaskListFactory is, for example. There is no such class, but AbstractTaskListFactory does have one-liner javadoc. Though I don't think it explain much. > Anyway, the cost of having no JavaDoc is that you make it much more difficult > for others to (a) learn about what's going on, and (b) interest them to help. I don't think we *make* anything. This is just the way it is and I don't think it would really stop someone who really want to contribute or build on top. > In comparison, the ECF codebase is well documented, has help specifically aimed at > developers, as well as JavaDoc > (http://help.eclipse.org/help33/topic/org.eclipse.ecf.doc/html/reference/ecfJavaDoc.html) > bundled with it. I suspect that both ECF and Mylyn are 'niche' in comparison to > the rest of the Eclipse codebase, but the difference between the two projects > with regards to documentation is hugely noticeable. Sure. However, even with the absent javadocs, I believe that Mylyn has much higher contribution and adoption rate comparing to most of the Eclipse projects, including ECF. Note that I am not arguing that no one should work on JavaDoc, I am just saying that its value can be successfully substituted by other means (i.e. source code bundled with install or retrieved from the version control, as well as more then one reference implementation of the api).
Marking as WONTFIX given the comments here.
Marking as closed.
Alex, technically it is not your call (and not my either) to decide if issue won't be fixed. Besides, nobody said that it won't be.
My take is that this is low priority for reasons that there is agreement on above. But Alex has good points on the utility of Javadoc, a key one being that Platform provides it so there is a standard. Since this will be low priority for the time being I'm marking it has helpwanted in case anyone wants to contribute a script for this earlier, but we should do it one way or another in the 3.0 time frame. Alex: regarding documentation priorities, we have basically been following the prioritization you outline in comment#6 and only prioritizing adding Javadocs to API classes (i.e. those not in ..internal.. packages). For specific documentation priorities that anyone wants to bring attention to we have bug 195450.
Providing better API documentation in the form of JavaDoc and tutorials that explain how to glue the individual classes together to build a connector or context bridge are key to get more integrators interested in the Mylyn as a framework. Now that the API is stabilized to a greater extend we should start adding more JavaDoc and incrementally improve the documentation.
Good points, bumping priority but leaving helpwanted for now since this would be a straightforward contribution and integrators have a good incentive to provide it.
To be honest, I'd be happy to just have the JavaDoc that's already there in the help pages, or at least viewable by a web browser. I can't download from CVS at work, but I can browse; and when I'm implementing a new connector, I don't really need to know the ins and outs of all of the internals, but I do want to know what the API I'm supposed to program against expects. Can I suggest that you have two bug reports; one for actually bundling what JavaDoc there currently is in the help documentation, and then another for improving the quality of the JavaDoc? This sounds like it's migrated from the former into the latter, whereas I'd be happy with just the former for now.
Let's continue to use this bug report for providing Javadoc. Requests for improving the Javadocs can go on bug 195450.
I generally agree that we should make the JavaDocs available with each release but at this point I am afraid that it could possibly be counterproductive. There is too little documentation and it too out-of-date to use it to program against the API. Often times looking at other code that uses or implements an API is required to understand and use it. There used to be source archives for people who weren't able to check out cvs, right? I can't find a link on the download page for the current release's source. Alex, you might want to take a look at cvsgrab [http://cvsgrab.sourceforge.net/] which allows you to download an entire repository over viewcvs.
Re comment 16; I think you're thinking of 'proxy.eclipse.org'. However, that doesn't work for us; if the firewall was 'only let stuff out on port 80' then it would do, but we've got a real HTTP proxy. So Eclipse sends a 'I LOVE YOU' message to the HTTP proxy, who then says 'What?' Sadly, if anonymous access over HTTPS was allowed, it would work; but that's for committers only. As for the JavaDoc being out of date; it still has some important information. One is 'implementors of this interface', another is subclassing, and a third is parameter names. The class files don't have parameter names, so it's a bit difficult to code blind against an API. The point is, something (even if it is very little and/or may contain errors) is better than nothing. Not only that, if someone does find out an error, they are more likely to raise a bug in support of bug 195450. I know I've raised several JavaDoc fixes against existing code without (a) being interested in the code, or (b) having the project checked out. It means I've not created patches for those projects, but the feedback's gotten in place and it's usually a trivial one to solve for a committer who does have the projects checked out already. I'll have a look at CVSGrab. Thanks.
(In reply to comment #17) > The class files don't have parameter names, so it's a bit > difficult to code blind against an API. Actually they do. I just checked and we have right settings for compiler.
Not when I subclassed them, they didn't ...
I should clarify. When I created the subclasses, I just got default parameter names. Mind you, it could be a setting on my workspace; I didn't check the content of the class files directly.
Maybe you should fill a bug to JDT about that...
As an FYI, I did the same thing again; in this case, created a new subclass of AbstractRepositoryConnection. The generated source had 'arg0', 'arg1' etc. throughout the code, even though I had the 'guess arg names' enabled. Indeed, even hovering the mouse over the super.methods resulted in the same argument signature of arg0, arg1 being displayed. So even if the .class file has argument names, it's basically useless to someone working with just binary files in JDT. To be honest, I'm close to giving up trying to write a connector simply because of the impenetrable suite of connections that are available without source. For example, it turns out that an AbstractQuery needs to have setRepository() called on it (even if you've handled it already) because otherwise you get a NPE in the stripSlashes (or something like that). That kind of thing isn't documented, even if you do look at the source via viewcvs. By the way, cvsgrab doesn't work for Mylyn. That's because the repository pages have ?root=ToolsProject or some such suffix, which cvsgrab doesn't grok. So whilst it might work for stuff in the 'main' eclipse project, it doesn't work for mylyn, or anything else in the tools/technology/datatools etc. repositories. Frankly, even a simple UML-like diagram of the main players is probably 50% of the documentation you need to get started.
(In reply to comment #22) > As an FYI, I did the same thing again; in this case, created a new subclass of > AbstractRepositoryConnection. The generated source had 'arg0', 'arg1' etc. > throughout the code, even though I had the 'guess arg names' enabled. Indeed, > even hovering the mouse over the super.methods resulted in the same argument > signature of arg0, arg1 being displayed. > So even if the .class file has argument names, it's basically useless to someone > working with just binary files in JDT. Cool! What is the bug number for JDT?
(In reply to comment #22) > So even if the .class file has argument names, it's basically useless to someone > working with just binary files in JDT. To be honest, I'm close to giving up > trying to write a connector simply because of the impenetrable suite of > connections that are available without source. For example, it turns out that an > AbstractQuery needs to have setRepository() called on it (even if you've handled > it already) because otherwise you get a NPE in the stripSlashes (or something > like that). Alex: for problems with writing connectors it's usually best to email mylyn-integrators@eclipse.org. For your specific problem you may want to file a new bug in case we can clarify or improve the behavior of the framework. As a practical matter, for the time being we have no way of doing a good job supporting integrators who do not check out the Mylyn sources due to PDE bug 157375 which prevents building of the nested JARs that ..mylyn.web.core uses. As such we are focusing our efforts on improving the experience for those who do check out the sources. I have clarified this in the Contributor Reference: http://wiki.eclipse.org/Mylyn_Contributor_Reference#Workspace
Mik: the PDE bug doesn't matter to me, because I'm not using web.core. And, as this bug requests, having any documentation is better than nothing; and nothing is what I've got now :-) As an idea, if you wanted to encourage people to write other connectors, having a 'sample' or template bug tracker (e.g. that uses a hashmap) might be a good thing to provide. I noticed that there's a lot of copy'n'paste between the various implementations at the moment; perhaps a template would make it easier for people to create new ones?
Eu: bug 196513
(In reply to comment #23) > (In reply to comment #22) > > As an FYI, I did the same thing again; in this case, created a new subclass of > > AbstractRepositoryConnection. The generated source had 'arg0', 'arg1' etc. It turns out that abstract methods don't have the Code attribute where the parameter name is stored, so for abstract methods of any type (be they interface or abstract class abstract methods) have no concept of parameter names. It's easily verifyable by looking at AbstractRepositoryConnector's abstract methods (e.g. taskUrlFrom...) ad you'll see they're all 'arg0' there, even if other concrete methods have names in their parameters. Incidentally, JDT does do this if there are parameter names there, but it can't if they are abstract, which is basically the problem that I raised. The solution ... make Javadoc available :-) And so we're back at bug 195723 ...
We've had relatively little interest and no votes for this. For 3.0 I propose that we focus on improving the Javadoc documentation and postpone the automatic creation of Javadocs HTML documents.
We now distribute SDK features from the update site which is the recommended way to access JavaDoc documentation.
Why not resolve this as WONTFIX then?
I still see value in doing this and unfortunately the SDK feature does no longer include JavaDoc documentation (bug 338996).
Mylyn has been restructured, and our issue tracking has moved to GitHub [1]. We are closing ~14K Bugzilla issues to give the new team a fresh start. If you feel that this issue is still relevant, please create a new one on GitHub. [1] https://github.com/orgs/eclipse-mylyn
