The IDE has autocomplete for code but doesn't have an automatic completion function for words in the comments, like the following comment:
/**
* this is a comment
* this is a co
*
*/
When I type co I want to get tips in some words that like: com, comm, comment ……
Is there any plugin that can do this?
You can try Tabnine, although it uses a lot of memory and slows down your computer.
Related
I have a fair understanding of both how to document code and how to write "generic documentation" using #mainpage, #page, #subpage and related tags.
I would need to include requirements/specification documentation for the code.
My problem is to keep this kind of documentation (conceptually distinct from code documentation) close to code implementing functionality (i.e.: at least in the same file, sometimes even near specific classes/functions/methods) but still be able to collect it in an orderly fashion and present it in the #mainpage, outside file/class hierarchy.
What I would ideally need is to be able to place specific #page, #section, #subsection etc. randomly in the various source files and then be able to #include them in a specific order into #mainpage or some other #subpage.
Even better would be to be able to include the same snippet in both class/function full doc (not #brief, of course) and in the "front matter" linked in #mainpage.
Global effect I need to have is to have a "specification document" where I detail what the various parts of the code need to implement and then the "normal class/function/whatever" documentation doxygen id very good at providing.
The catch (i.e.: what I don't know how to do) is I would like to keep "specification" and implementation together in the source, but separate them in documentation, i.e.:
General Description: easy, this goes into #mainpage
Requirements: most likely at top of source file implementing them, how do I link/include in main page?
Specification: either right after Requirements at top of file or somewhere near class/function implementing it; also here I don't know how to link/include in "front matter" AKA: #mainpage.
Normal code documentation: here only thing I don't know is how include in class/function description the same "doc snippet" already used for (2) and (3).
Is this possible?
If so, what's the best practice?
Note: I could get the effect using a separate file for each "doc snippet" and then #includeing it in the right places, but that would defeat the whole purpose that's keep Requirements/Specification/code together while separating them in different sections in the resulting documentation.
Update: following #albert comment I tried the following:
in a standard Doxygen comment I added markers:
/**
* Initialization function.
*
* [AM_init]
* It needs to do a long series of tests to ensure AM can actually work.
*
* It should also allocate all dynamic memory needed to avoid runtime failures.
*
...
* It will be responsibility of system-level daemon to take appropriate action.
* [AM_init]
*
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port) {
...
in the "front matter" definition I have (among other things):
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
The function documentation is rendered correctly (i.e.: the markers are removed)
OTOH the initialization page is "somewhat incomplete":
Initialization
It needs to do a long series of tests to ensure AM can actually work.
that's it.
Apparently the tag is found, but only the first line is actually included.
Further Update: Following #albert answer (accepted) I had success, but the following caveats:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: <br/> for line termination) because Markdown constructs ("double newline", in the above case) are notrecognized.
In retrospect I think "Note" in Doxygen \snippet['{'option'}'] <file-name> ( block_id ) documentation addresses, more or less all the above, but I find it very cryptic and I would never have understood the implications without my nose being rubbed into them.
The last one is very annoying because I use a lot Lists and Tables and while HTML syntax is much more powerful, it is also much more difficult to write and to read in sources.
Finding a way to lift this limitation would be "very nice".
With the following code and the current doxygen version (1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)) but also with the 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b) version, I get good result:
bb.h
/// \file
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
CommandHandler.c
/// \file
/**
* Initialization function.
*/
/* [AM_init]
It needs to do a long series of tests to ensure AM can actually work.<br>
It should also allocate all dynamic memory needed to avoid runtime failures.<br>
It will be responsibility of system-level daemon to take appropriate action.<br>
[AM_init]
*/
/**
* \snippet{doc} this AM_init
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port){}
Doxyfile
EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES
Note: OP rightfully mentioned in further update that there are some things to take care of:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: for line termination) because Markdown constructs ("double newline", in the above case) are not recognized.
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.
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.
Hopefully a simple question.
I've started using NetBeans for a new multi-developer PHP project I am working on. One thing I have noticed in scripts in the past is a section in the PHPDoc at the top with something similar to
/**
* PDO Database Configuration
* Last Updated: %Date: 15/03/2011, 22:31:04 GMT (Tue 15th Mar 2011)%
*
* #author lethalMango
...
*/
Is there a method to get that "Last Updated:" section to update automatically on save?
Cheers
As Melv says, a common way of doing is via the version control system. This is a better approach than relying on the IDE since it only needs setting up once server-side rather than on every client.
If you're using Subversion, you'd do this with properties.
Something like this, assuming yourfile.php has been added to svn:
svn propset svn:keywords "LastChangedDate" yourfile.php
Then add the string $LastChangedDate$ to the file, and every time the file is committed the keyword will be expanded to include the date.
I'm pretty sure Netbeans doesn't give you anything like that. I don't know of a plugin that gives you a hook to it either, but there are definitely ways of doing this sort of thing on versioning commits and/or in build tools, so that might be the best way to tackle it.
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.