I am using Ecliplse and when hovering my mouse over a method name e.g. Integer.valueOf(0);
the Javadoc gives me parameters info:
Parameters:
i - an int value.
However, if I write my own method (and doc comment):
/**
* #param i an {#code int} value.
*/
public static void bar(int i) {
}
I would have the following when placing my mouse over my method name
Parameters:
i an int value.
So, why the appeared "javadocs" (at mouse hover) are rendered with different format, even if I write exactly the same comment as found in the source file of java.lang.Integer?
I kind of dislike the sencond format with bold param names and would like to stick to the first format. Any way I can configure Eclipse to achieve that? Please could someone help me to demystify...Many thanks
The difference stems from the individual templates (doclets) you can use when generating Javadoc. If Eclipse generates Javadoc (on-the-fly) from comments in code it obviously uses a template that omits the '-'. When Oracle generated the official API documentation for the JRE it used a template that generates a '-'.
So, why do you see a '-' in Eclipse when you browse JRE code but not in your own code? It seems like you configured the JRE in Eclipse (Window > Preferences > Java > Installed JREs) such that the Javadoc is available in the file system but the JRE source is not. Hence, Eclipse will show you the official Oracle version rather then generating it on-the-fly from source.
Related
Not a big deal, I can ignore it, but it's annoying.
Using: Eclipse Photon 2018-06. PHP 5.6. CentOS 7.
There are thousands of lines of code, often with formatted comment blocks before function definitions. E.g.:
1 /**
2 * MyKoolFunction
3 * Does Kool Things
4 * #param arr $input_array
5 */
6 public function MyKoolFunction($input_array=array()) {
etc.
Then Eclipse flags an error at the line 4, that:
arr cannot be resolved to a type
THIS IS ONLY A COMMENT. The original author used "arr" instead of "array". Who cares whether it can be resolved to a type? There's no issue with the web server, which properly ignores comments. Everybody (except Eclipse) will read it and understand the meaning.
There are dozens of permutations of this all over the place, "unknown", dollar signs left off, misspelled types, even types left out -- then it flags the word after the variable. E.g.:
* #param $name the name of the client
Flags "the".
I know it's probably doing this for some automatic documentation tool, but I don't care about such.
Is there a way to turn it off?
You can disable type validation in PDT, go to preferences -> PHP -> Validation -> Errors/Warning
You can't disable PHPDoc validation only.
PHPDoc isn't simple comment, it by design instruct IDE how to interpret code
Because you have "arr" rather than array, during code assist PDT will search arr class, so you might si invalid Code Assist.
Short version:
If I wanted to develop a completely new jsDoc template from scratch, what would I have to read to understand what jsDoc does, what interface my template must provide and what data I get to work with?
Long version:
I've been using jsDoc for a while now and have come across some tags that I would like to add and overview pages that I would like to have generated out of my documentation. Up to now I solved all my "user problems" with usejsdoc.org. I even managed to add a new jsdoc plugin that adds some tags. However, I can't find any developer documentation on how to create templates for jsdoc. I use ink-docstrap so I clicked my way through the template-folder (publish.js, /tmpl, etc.) and somehow got the idea of how everything works. But its very very time consuming.
What should I read to become a jsDoc template pro?
These instructions are the closest I could find:
To create or use your own template:
Create a folder with the same name as your template (for example, mycooltemplate).
Within the template folder, create a file named publish.js. This file must be a CommonJS module that exports a method named publish.
For example:
/** #module publish */
/**
* Generate documentation output.
*
* #param {TAFFY} data - A TaffyDB collection representing
* all the symbols documented in your code.
* #param {object} opts - An object with options information.
*/
exports.publish = function(data, opts) {
// do stuff here to generate your output files
};
To invoke JSDoc 3 with your own template, use the -t command line option, and specify the path to your template folder:
./jsdoc mycode.js -t /path/to/mycooltemplate
Failing that, you can read the source code!
I am running into a similar difficulty with lack of documentation. There is a GitHub issue that has been open for 7 years on this: Provide docs that explain how templates work.
The only example I've found so far of a custom template that doesn't look like just a modified version of the default is Ramda's documentation. It looks like they use a completely custom publish.js script that uses handlebars.js instead of underscore.js templates, constructs a non-hierarchical nav, pulls info from #sig and #category tags, and uses links to github for 'view source' instead of rendering its own html pages for source code.
Some of their code will be difficult to understand unless you are familiar with Ramda and functional programming (they use Ramda itself in their version of publish.js) but dumping out the values of data and docs during execution should help provide insight into what is going on.
It is helpful as well that their template is a single file so you don't have to jump between a lot of partial template files to follow how the doc is constructed.
I've just published my own new jsdoc theme. What I did is I simply copied the default template: https://github.com/jsdoc3/jsdoc/tree/master/templates/default, and worked on that.
I also managed to add grunt with the following features:
* transcompile + minify js files
* parse sass styles and minify them
* refresh the docs when you change something
You can see how it works here: https://github.com/SoftwareBrothers/better-docs
you can customize one of existing templates (default, haruki or silent):
go into node_modules/jsdoc/template and grab on of them into your app directory outside node_modules.
feel free to rename the dir ex: jsdoc-template.
open jsdoc-template update/customize the content as you want. ex: open publish.js find Home and replace My Js App.
update jsdoc.json by adding:
"opts": {
"template": "jsdoc-template"
}
another option to use one of those templates too: jsdoc3 template list examples
Followup to my previous comment about Ramda's JSDoc template. I've since created a customized version of it and published it on GitHub at https://github.com/eluv-io/elv-ramdoc
This is tailored for my company's projects, but it may be helpful as another learning tool. It adds a 'Show private' checkbox, updates Bootstrap to v5.13, replaces Handlebars with Pug, adds JSDoc comments to the publish.js script itself, and supports setting an environment variable to dump data to console during doc generation.
I am developing a component which generates code based on templates inside java class. The project use clearcase as SCM. After the code update, the files are in read-only state. If i am adding anything to any java class, i have to make it hijack and paste the source code templates inside the class. Let's suppose the jAutoDoc plugin which is used for adding comment. If user select a class, click on generate comment. The comment will not paste if the file is not in write mode.
Clearcase Plugin Vendor : IBM Rational.
Eclipse Version : 3.5
Please help. Is there any way to do hijack a file from java code?
Thanks in advance..
Thanks VonC.
For making a java file in write mode through eclipse JDT API. This method will set the preference "read only" of the resource to "false".
private static void setCompilationUnitWriteMode(ICompilationUnit cu) throws CoreException {
ResourceAttributes resourceAttributes = cu.getResource().getResourceAttributes();
if (resourceAttributes != null) {
// Setting Writemode true
resourceAttributes.setReadOnly(false);
cu.getResource().setResourceAttributes(resourceAttributes);
}
}
For Non Java Resource
First create the IFile object, set the preference "read only" of the resource to "false".
IFile file = path.getFile()
file.getFile().getResourceAttributes();
if (resourceAttributes != null) {
resourceAttributes.setReadOnly(false);
file.setResourceAttributes(resourceAttributes);
}
Hijacking files only means making them read - write through an OS-based operation. (for snapshot view only, not dynamic ones)
The question is though: do you need to version your classes completed by your plugin?
Because in that case, a cleartool checkout is more appropriate.
Otherwise, read write is enough, changing file attribute through java.
I tried
s=Normalizer.normalize(s, Normalizer.Form.NFD).replaceAll("[^\\p{ASCII}]", "");
But it seems that GWT API doesn't provide such fonction.
I tried also :
s=s.replace("é",e);
But it doesn't work either
The scenario is I'am trying to générate token from the clicked Widget's text for the history management
You can take ASCII folding filter from Lucene and add to your project. You can just take foldToASCII() method from ASCIIFoldingFilter (the method does not have any dependencies). There is also a patch in Jira that has a full class for that without any dependencies - see here. It should be compiled by GWT without any problems. License should be also OK, since it is Apache License, but don't quote me on it - you should ask a real lawyer.
#okrasz, the foldToASCII() worked but I found a shorter one Transform a String to URL standard String in Java
In eclipse, when I want to document a function (in java or javascript source) I can just type /**, then hit enter, and I get a comment like this
/**
*
* Fluctuates all variables to more compatibly foo all the bars
*
* #PARAM {int} foo
*/
function flucvar (foo) {
}
When hitting enter inside the comment, eclipse automatically adds extra * at the beginning of each line.
Now I'm just getting into my textmate groove, and finding myself missing this little bit of functionality. Is there an equivilent bundle or command or something that would allow me to produce similar comments in textmate?
You need to create two snippets (I have them in the Source bundle).
First create a snippet for inserting JavaDoc comments. The snippet contains the following:
/**
* $0
*/
I have the snippet Activation set to Tab Trigger, using /** as the activation string. Every time I write /** and press Tab, I get a JavaDoc comment block. You can also use a keyboard shortcut if you like.
The second snippet is for continuing existing JavaDoc comments. The snippet contents are:
* $0
Note that there is an empty line before the * $0 line. Set Activation to Key Equivalent and the trigger key to return key. Set the Scope Selector string to comment.documentation.
Now if your language bundle supports the comment.documentation scope (like all of the included bundles seem to do), you should have working shortcuts for JavaDoc comments.
I took a look at TextMate's Java bundle, and I didn't see anything about inserting JavaDoc comments. However, it shouldn't be that hard to add such a feature to your Java bundle. It would likely be a Snippet, which you can read about in Chapter 7 of the TextMate manual (accessed from Help -> TextMate Help).
thanks for that answer. I just found this post on the macromates site
http://blog.macromates.com/2006/customization-screencast/
this appears to have a video/mailing list post that explains precisely how to do this.