I'm want to document the asymptotic runtime of a function, as it will be used for algorithm-engineering for graph problems.
What's the most idiomatic way to do this? Is there a way to create new tags in Javadoc like #return or #author?
I provided an example below, which is the method to delete a vertex in the graph.
/**
* Runtime: O( degreeOf(v) ) because every neighbour of [v] also needs to be updated.
*/
fun deleteVertex(v: V): SimpleGraph<V> {
if (v in m.keys) {
for (nb in m[v]!!)
m[nb]!!.remove(v)
m.remove(v)
}
return this
}
To create custom tags for Javadocs, simply follow these instructions.
You can create other customizations for Javadoc. For example, in Eclipse, you can create "templates" so that when you create new classes or add new methods, the IDE automatically apply this template to add a (Javadoc) comment formatted in the prescribed style of the template you applied. You can save these templates in an XML file so that you could share it with other members of your team. I am sure that IntelliJ and other modern IDEs will have similar features. I am just more familiarized with Eclipse. Here is a video I created many years ago on how to create a Code Formatter in Eclipse. If you advance to the 1:48 mark, you will see "Code Template" right above the "Code Formatter" option I selected in the video. Creating a code template is much easier than a formatter.
To do this, simply click on Windows > Preferences menu to get the Preferences popup. There, select Java > Code Style > Code Templates. in the right pane, expand Comments and select the component you wish to create a comment template for, for example Methods. Click Edit button and format the Javadoc comment to your liking. Obviously, you will have to do a bit of research to get really creative with your comments. For example, you might need to figure out how to use system variables or create your own. For example, in the image below, I made use the year variable to apply the current year whenever I create a new class.
Once you finish with all your template customizations, simply click the Export button and use the File Chooser dialog to save the file wherever you would like.
One last tip, if you need to embed code snippets in your Javadocs, you can follow the recommendations in this article. I do this very often. Sometimes I find it useful to embed a few lines of code to illustrate different use cases for the method. That way, other developers can see how to use the method in the correct context.
Related
So, for example, if I were to insert a Javadoc comment for a field from some external source on web, I would copy paste the relevant part from the website and then move on to my Class to incorporate the copied content as a Javadoc comment for the field.
But the problem is, I can't find any support from Intellij regarding this. Currently, I have to type, /** + Enter to generate a stub then paste the content there, which doesn't get properly pasted - I mean, a paragraph of 5 lines comes as a single long line and the Javadoc * on the side disappears.
I was looking for something like, paste the content copied raw in the place then select it and if Intellij provides some shortcut to wrap it as a Javadoc comment, do it except I couldn't find any support from Intellij for this approach.
So my question is, does anyone know of any such tool/plugin/built-in Intellij support or any other workaround for doing this as this is time consuming?
You will have to start with the /** and Return to get the basic javadoc comment. Then you can paste your text with ctrl+V (⌘+V on OSX) as the cursor is positioned at the right place.
All that is left then is use the keyboard shortcut that is defined for reformatting. In the menu you will find that under _Code/Reformat Code, on my Mac it is ⌘+⌥+L.
I want to add references to other elements inside javadoc. The javadoc should look similar to:
/**
* ...
* #my.tag SomeElement
*/
I want to reuse the existing Java editor inside Eclipse. Of course I can type above javadoc already, however I'd like to add some features:
Navigation: upon Ctrl-Click / F3 I want to navigate to the editor showing SomeElement
Auto-completion: Ctrl-Space should complete the text / show valid alternatives
Checking: I want to create a warning marker and underline the SomeElement if it cannot be found
I already figured out that I can do the auto-completion by using the extension point org.eclipse.jdt.ui.javaCompletionProposalComputer, though this seems to be little more complex than I had hoped, so I might be on the wrong track here?
For checking my elements I might be able to use org.eclipse.jdt.core.compilationParticipant, which can generate markers upon compilation which afaik happens with every save operation.
But how can I can manage the navigation feature? Any pointers are welcome!
For navigation you can provide a Hyperlink Detector. You'll want to look at how the Java Editor and its existing detectors are declared in the org.eclipse.jdt.ui plug-in to determine the correct target ID.
For a custom Eclipse plugin, I've been looking into creating a perspective that will help organize views in a way that makes work easier for the editors, with the main requirement that we would like to simultaneously see two editor areas in the perspective.
Our plugin uses two new editor types: A "Workflow Editor" (WE) and a "Trial Editor" (TE) We would like to make sure that all instances of the WE are opened in one area of the perspective, and all in the TE are opened in a separate area.
Essentially, it looks like the perspective whose link is below, except that in place of the Java editing views in the top-right, we'd have the WE views, and in place of the text editing views in the bottom-right, we would have the TE views.
(http://dl.dropbox.com/u/4148918/eclipse-multi-editor.jpg)
I took a look at the tutorial on creating perspectives here: http://www.eclipse.org/articles/using-perspectives/PerspectiveArticle.html . While this is a good start, it looks like by default perspective layouts only support one editor area, in which all editor views are opened:
public void defineLayout(IPageLayout layout) {
// Editors are placed for free.
String editorArea = layout.getEditorArea();
// Place navigator and outline to left of
// editor area.
IFolderLayout left =
layout.createFolder("left", IPageLayout.LEFT, (float) 0.26, editorArea);
left.addView(IPageLayout.ID_RES_NAV);
left.addView(IPageLayout.ID_OUTLINE);
}
How would one customize this layout such that it has two editor areas instead of one, each of which supports the editing of one distinct file type? While I have found a couple of online samples where the editor pane is split, these examples don't inherently support the automatic opening of one file type in one of the editors vs. the other, which is a desired feature for this plugin.
Alternatively, could one use 'folders,' and have instances of each editor open in these specialized folders? If so, what would be the entry point for defining new views associated with these editors, like those enumerated with "IPageLayout.ID_*" above?
Would much appreciate any advice someone has -- I think it's a cool problem to get two editors to show up simultaneously in different sections of an eclipse plugin, and it would be great if we could get it to work!
How would one customize this layout such that it has two editor areas instead of one, each of which supports the editing of one distinct file type?
You can't. As you've mentioned, you can only define one editor area in an Eclipse perspective.
You have two choices. Your first choice is to create your own multi page editor with a "Workflow Editor" (WE) on one page and a "Trial Editor" (TE) on the other page.
You second choice is to build an Eclipse workspace from the ground up with two (or more) editor areas. You can look through the Eclipse source for help, but you would basically be building your own Eclipse.
I have a question related to hyperlinks in java.
How can I set hyperlink in java file to point to another java file loaded on the text editor in Eclipse, when I have the filename and code line:
ex. Test.java:102
How to show the given code line of that file on the text editor?
Thank you!
The Java language does not know hyperlinks.
JavaDoc does know hyperlinks, which you can easily access in the Eclipse editor by typing either the # sign and choose a local member or by typing the name of an external class and hitting controlspace, then choose the right link.
Fortunately, you cannot directly create links to lines. Lines change in time, the contract of the class (the description of the methods/fields) is what should remain relatively static. When configured correctly, Eclipse will even change your links if you refactor your code (e.g. rename your method or class).
You cannot create hyperlinks to lines -afaik, but you can create links to fields or functions in javadoc:
/**
* {#link package.ClassName#fieldOrFunction}
*/
doing it like that allows you to ctrl-click on the "fieldOrFunction" and jumps right there (at least in eclipse)
2 years later, I know...
If you are looking for hyperlinks from any file surround it with parenthesis like so
(AnotherClass.java:52)
ctrl click will take you there if it knows of that class.
is it possible, in Eclipse, to mark certain lines with Shortcuts and be able to quickly jump to those lines?
Example: Let's say I have maintenanceHeavyMethod() at line 120 in my class, gameLoop() at line 800 and some listener at line 1460.
I'd like to f.ex. press CTRL+SHIFT+1, 2, 3 etc. to mark those positions, and then use f.ex. CTRL+1, 2, 3 to immediately jump to them. I don't like split-screens etc, but I need to jump around when writing.
Is there such a feature?
I'm using latest Eclipse to write Java-programs.
You can add Bookmarks in your code. Select the code fragment you want to bookmark and then go to Edit > Add Bookmark... (also possible via the menu available with a right-click in the left hand column of the editor, like breakpoints).
Then, add the Bookmarks view. Select Window > Show View > Other... > Bookmarks and you'll get something like this:
Sadly, I don't think you can bind a shortcut to a particular bookmark.
Just in case, the shortcut to jump to a particular line is CTRL+L.
That would be best taken care by mylyn:
Define a task with this three method, and you will be to see only those 3 in the package explorer view
To jump to a particular method, I use ctrl+o and then start typing the method. If you're a proficient typist, this shouldn't take any longer; keep in mind that you only have to start typing the name of the method.
Unfortunately this isn't a proper solution for jumping to a line of code within a method.
You can jump to methods by using the outline view. Outline view shows all the Methods, Fields, and Inner-Classes (and their methods and fields and inner-classes...etc) of the source file you currently have open. I personally prefer this method, unless I have a stacktrace and know which line I want to jump to, in which case I use ctrl+L.