Bugzilla – Full Text Bug Listing
| Summary: | Eclipse.org has inconsistent documentation structure between projects [was: Provide an 'Eclipse Snippets' corner on the Eclipse.org website?] | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Community | Reporter: | Christophe Cornu <christophe.cornu+eclipse> | ||||
| Component: | Website | Assignee: | phoenix.ui <phoenix.ui-inbox> | ||||
| Status: | RESOLVED WONTFIX | QA Contact: | |||||
| Severity: | enhancement | ||||||
| Priority: | P3 | CC: | chris.guindon, cross-project.inbox, jeem, john.arthorne, Mike_Wilson, n.a.edgar, sxenos, tobias_widmer, Tod_Creasey, tom.schindl, wayne.beaton | ||||
| Version: | unspecified | ||||||
| Target Milestone: | --- | ||||||
| Hardware: | PC | ||||||
| OS: | All | ||||||
| Whiteboard: | |||||||
| Attachments: |
|
||||||
*** Bug 176660 has been marked as a duplicate of this bug. *** Wouldn't the Wiki be a great place for this type of content? This would be a good way to get this started. We could provide a sample wiki template page ComponentSnippets. Snippets could be embedded in a verbatim block (short/partial snippets). Or referencing an attached/external file (e.g. SWT snippet uses real java files managed by CVS so it's easy to verify they compile with the latest SDK). Regardless of the technology - wiki, custom buzilla type 'snippet', snippet junits, next generation javadoc .. - I was curious to see if the 'snippets' concept could be extended from SWT to other components. If it doesn't appeal to other component owners then we should close this (e.g. the committers on this CC list). Otherwise we could refine its format on the wiki website with interested committers from different teams. We don't want to add yet another layer of doc that gets out of date. But it has been so powerful to expose our SWT common use cases, APIs and programming idioms I just wish other components could advertize their value added in a similar fashion. Library code + Javadoc + Snippets and a new developer is good to go. Is this related somehow? http://tom-eclipse-dev.blogspot.com/2007/06/why-do-we-devs-need-code-snippets.html Completely right on. I hope SWT and JFace can now 'infest' other components with the culture of snippets :-) Nebula also already provides a snippet project so we currently have: - SWT - JFace - Nebula as Snippet contributors :-) I think the problem is the more we go away from GUI programming the harder it gets to provide snippets how to solve such common tasks things get too complex to present in a few lines of code. Maybe we should make a dedicated wiki page accumulating all links to Snippets even when they are from external resources like http://www.java2s.com/Code/JavaAPI/CatalogJavaAPI.htm who offer SWT/JFace snippets. Moving to Community/Website (In reply to comment #3) > Regardless of the technology - wiki, custom buzilla type 'snippet', snippet > junits, next generation javadoc .. - I was curious to see if the 'snippets' > concept could be extended from SWT to other components. > > If it doesn't appeal to other component owners then we should close this (e.g. > the committers on this CC list). Christophe, I'm not sure what I can do to help you out with this. Have you tried using the Wiki? Created attachment 89452 [details]
Eclipse.org has inconsistent documentation structure between projects
This attachment shows the Eclipse.org SWT website and the Eclipse.org EMF website. See how the documentation is presented differently in each project.
I wish Eclipse.org projects would expose documentation such as javadoc and snippets in a way that is easy to find - as easy as in the SWT website. I would like to be able to browse Eclipse.org projects and quickly explore their javadoc and snippets. It could be as simple as asking project leads to adopt a standard wiki template with a 'javadoc' and 'snippets' link for example.
I understand you may not do anything about it. I'll keep talking to people at Eclipse.org to suggest ways we can make it more efficient to navigate through javadoc and snippets cross projects :-) Feel free to close this bug as WONTFIX.
I'll change the title of this bug to reflect comment 9, as that seems to be the bigger issue here. cc'ing the cross-project alias for completeness. This isn't a Phoenix issue per se, but I can see Phoenix being a facilitator here. Closing this bug as WONT FIX. |
Eclipse projects add lots of exciting API's with every milestone and release. As such, plugin programmers want to be aware of new programming styles, new innovative or revisited ways to hook into Eclipse components. New and Noteworthy section is priceless to Eclipse users. We could use something similar with a focus on Eclipse API consumers. Committers producing new API's, deprecating existing API's could maintain a blog or a mailing list with the new cool tricks they want everyone to take advantage of in the latest release. And their recommended way of efficiently using their APIs. A little bit like the best seller 'Effective C++' cooking book from Scott Meyers, applied live through every milestone/release of Eclipse APIs. E.g. Tobias taught me how I could replace the 7 seven lines below calling in the JFace component final IPreferenceNode targetNode1 = new PreferenceNode(.., ..); final IPreferenceNode targetNode2 = new PreferenceNode(.., ..); PreferenceManager manager = new PreferenceManager(); manager.addToRoot(targetNode1); manager.addToRoot(targetNode2); final PreferenceDialog dialog = new PreferenceDialog(parent.getShell(), manager); dialog.open(); With this better API which buys me the new JFace preference filtering support for free PreferencesUtil.createPreferenceDialogOn(parent.getShell(), .., new String[] { .., ..}, null).open(); JFace committer who first offered this API contributes a new entry to the 'Eclipse Snippets' section of our website. --------------------------- Component: org.eclipse.jface Title: How to open a preference dialog from within a view Compatibility: since Eclipse 3.1 Committer: Nick@eclipse.org Submitted: June 5th 2004 Votes: 576 Status: Active (can be deprecated if author thinks it is no longer applicable) Description: To open a preference dialog use the new JFace utility API as in below. PreferencesUtil.createPreferenceDialogOn(parent.getShell(), .., new String[] { .., ..}, null).open(); --------------------------- I could periodically read or search through this section and learn how to better use the Eclipse APIs and vote for the snippets useful to me. SWT could add entries pointing to their list of snippets maintained at www.eclipse.org/swt/snippets/ whenever they add a new snippet. Other teams not yet 'snippet aware' could start advertizing the cool workflows their unknown APIs support. Once a year, we elect the best snippet with the most votes at EclipseCon :-) Wondering what you think and if you like it what is the best channel to push for and refine this suggestion?