I tried googling this question a lot but could not find the answer to exact question. I also read this question: Does the javadoc tool recognize comments inside methods?
So my question is kind-of a follow-up to this. I know that default JavaDoc tool would simple ignore any javadoc comments inside methods, but can we somehow make it read those comments too and may be try handling them on our customer doclets/ taglets? I tried writing my own doclet and taglet as well but since JavaDoc would completely ignore the comments inside methods, I could not succeed.
For example, suppose I have the following code:
public void methodX() {
/**
* #MyTag This is a sample javadoc comment with custom tag
*/
}
Is there a way to make JavaDoc not ignore the comment inside methodX? I could handle the response in a custom doclet if javadoc could parse and provide the comment text.
Reason to try this:
I guess it would be helpful to know why I'm looking for such a requirement. Basically we have a lot of configuration driven coding where these configurations are stored in DB (So that we could simply change the configuration at runtime without having to go through the BRD process again). So we are planning to document those configurations at a central place. And instead of keeping the code and document separate, we also think it would be wise to keep the documentation closer to code itself so that any code updations could also possibly update the documentation. Publishing to central place can be taken care of via doclets/ taglets but only if JavaDoc could read those comments inside methods.
So is there a possibility of making JavaDoc tool read through comments inside methods as well? Or else we would have to try and write our own comments parser similar to JavaDoc for this.
So I did a little digging around and seeing that no-one has answered the question, it seems people are (maybe) not sure about the possibility.
Based on what I found, it doesn't seem feasible to have the JavaDoc tool parse the comments inside methods. The reason being, JavaDoc doesn't even get those comment texts to parse. Now, what I mean here is, JavaDoc relies on the JDK compiler (the API of-course) to have the Java code converted into tokens and trees and then gets all the comments from there. So unless you are okay modifying the JDK compiler itself to make it "Do Not Ignore" the comments inside methods, you can't make JavaDoc to read comments inside method.
Oh! And for the part of solving our problem, we're, for now, restricting to define JavaDocs with custom Tags for the constants we used and have the comments processed via a Custom Taglet to handle the new Tags.
Related
Is there a way to add to a description in a methods quick documentation? I have some methods I created that I plan to use later down on the line and want to add to its quick documentation to remind myself what the method is for in case I forget, without having to go into the method itself to read comments describing what the method does.
Is there a way to add to a description in a methods quick documentation?
The best way to document your methods is giving them (and their parameters) meaningful names.
Comments should not repeat what the code expresses itself. But no generator will ever look into your head to extract your intention from there. It rather will analyze the code and build the comment based on what's already written.
Therefore (meaningful) comments cannot be generated.
There are two valid reasons why you should write comments (yourself):
Interfaces
Interfaces need (JavaDoc) comments to explain the contract behind the method, to express the callers expectation as a help for the implementer.
odd ball solutions
Is there something in your code done in an unusual way?
Then add a comment why you did it so.
There might also be comments for legal reasons e.g. copyright marks, license texts and alike. But there should not be any other comment then this, especially nothing generated.
If you want to put comments in a single place for an entire project, or keep comments co-located with a set of files, try using a README. These are usually written in Markdown for easy conversion to beautifully formatted HTML for easier reading. Try an online markdown editor.
I'm using javadocs generated by the javadoc Ant task to document a web service, and I want to exclude some constructors from the output. How do I do that?
There is no way to do this for public methods. The standard practice (even in quite a few JDK classes) is to indicate that the method or constructor is not meant for public use.
There is a plan to add an #exclude tag in the future:
#exclude - for API to be excluded from
generation by Javadoc. Programmer
would mark a class, interface,
constructor, method or field with
#exclude. Presence of tag would cause
API to be excluded from the generated
documentation. Text following tag
could explain reason for exclusion,
but would be ignored by Javadoc.
(Formerly proposed as #hide, but the
term "hide" is more appropriate for
run-time dynamic show/hide
capability.) For more discussion, see:
Feature Request #4058216 in Developer
Connection.
Isn't excluding something public from your documentation just a variation on "security through obscurity" (or rather, "documentation through obscurity")? If the constructor is part of your code's API, it's available for them to use. If they find out about it and use it, is that their fault (since you made it public in the first place)?
If you can change the constructor's visibility or remove it altogether, I would go for that. If you cannot remove it from the API, make it known in the Javadoc for the constructor that it's not intended for use via web service. That way you've established a contract with users of your API, informing them not to use it.
It's better to document that it should not be used instead of not documenting it at all (if it's public). Not documenting it adds risk that it gets inadvertently used, and then the client code using it breaks when you change the implementation.
See the relevant Javadoc FAQ entry.
There is currently no Javadoc option
to hide, exclude or suppress public
members from the javadoc-generated
documentation.
It would appear this is not possible in the vanilla Javadoc, but some workarounds are offered.
Currently the simplest solution is to start the javadoc comment with #deprecated, and then pass -nodeprecated to the javadoc command. Of course, this may not be acceptable if you have actual deprecated items which you nevertheless want to include in the documentation.
Change the method access level of the method, then use the use the javadoc task's access-level filtering attributes, private, package, etc. Only do this if it makes sense in your code, though, e.g., method that had inappropriately loose access levels.
For constructors, for example, you could reduce the access level to package, then create a factory class in the same package that provides construction access outside the package. The factory class can be easily filtered from the javadocs. Kind of hacky, but it works.
Give Chris Nokleberg's ExcludeDoclet a try:
http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html
I've just been experimenting with it and it seems to do the trick.
The closes I got is to use Doclava, which has the #hide tag you can specify in method documentation.
Simple question here. Is there any point in applying javadocs to methods in a javafx application.
For starters - the majority of my method headers are formatted as private (with #FXML annotation).
I am using some public methods - but what is the point in javadocs if the end user uses a GUI to interact with the application and my application isn't an API? Obviously, all my methods are concisely commented - but I don't see what benefit javadocs will have for users or future developers of the code.
Am I wrong? If so, I'd really appreciate your views on this.
Many thanks.
Please take a look at https://softwareengineering.stackexchange.com/questions/85910/is-it-wrong-not-to-create-javadoc-for-my-code
In theory, meaningful documentation is never bad, and therefore every method you can document in a meaningful way should be documented.
In practice, it comes down to who the "audience" for the documentation is, to team-agreement, and to personal choice.
Things to consider are:
Your audience can be a maintenance developer, which, nevermind other persons, may be yourself, after 3 years without working or visiting the project, and after you have forgotten the details of how it all works.
In case of Javadoc and similar documentation tools and standards, even for private methods (usually not outputted to external doc files by default), many IDEs support Javadocs (or similar) and implement extra-features based on them. NetBeans, for example, can display tooltips containing the types, names, and if you documented them, purposes of classes, methods, and input and output parameters and vars. Eliminating the need to open files and/or look at source-code inline-comments if and when you forget something.
For framework code, I always Javadoc all public and protected members. For application code, I generally don't bother with Javadoc comments, but I do use inline comments to explain what a method is doing.
For private methods (whether framework or app code), I don't use Javadoc at all, since they aren't included in the Javadoc output by default. I do use inline comments for private members, though.
Is there any diff tool specifically for Java that doesn't just highlight differences in a file, but is more complex?
By more complex I mean it'd take 2 input files, the same class file of different versions, and tell me things like:
Field names changed
New methods added
Deleted methods
Methods whose signatures have changed
Methods whose implementations have changed (not interested in any more detail than that)
Done some Googling and can't find anything like this...I figure it could be useful in determining whether or not changes to dependencies would require a rebuild of a particular module.
Thanks in advance
Edit:
I suppose I should clarify:
I'm not bothered about a GUI for the tool, it'd be something I'm interested in calling programmatically.
And as for my reasoning:
To workout if I need to rebuild certain modules/components if their dependencies have changed (which could save us around 1 hour per component)... More detailed explanation but I don't really see it as important.
To be used to analyse changes made to certain components that we are trying to lock down and rely on as being more stable, we are attempting to ensure that only very rarely should method signatures change in a particular component.
You said above that Clirr is what you're looking for.
But for others with slightly differet needs, I'd like to recommend JDiff. Both have pros and cons, but for my needs I ended up using JDiff. I don't think it'll satisfy your last bullet point and it's difficult to call programmatically. What it does do is generate a useful report for API differences.
I recently read an article talking about the Java annotations, and on this latter comes the #Generated one. They say that it is used for automatically generate code.
Could someone explain me that in further with a little example ?
All what i found on the net was some pro question or something beyond what i was looking for.
As per the JavaDoc:
The Generated annoation is used to mark source code that has been generated. It can also be used to differentiate user written code from generated code in a single file.
#Generated is used by meta-programs such as Auto/Value which generate source code so you don't have to manually write it. If you're writing a .java file by hand (which is normally what one does), don't use #Generated.
Fox example are good and bad policies on the border between generated and written code. Way of thinking is (i belive) different in compiled (static) languages, nad interpreted / dynamic.
Worst is to modify generated code (will be lost at next generation, or next generation is then prohibited)
Usually is accepted to derive (manual) class from generated, or generate class what extends core "manual" class.
If someone know good policies in this area, please comment.
Some code linters use the annotation to skip generated code. For example, it doesn't make sense to calculate cyclomatic complexity on generated code.