I'm trying to figure out if there is a way to make PhpStorm format dockblocks according to Laravel's guide
I know how to use settings in order to set it up as PSR-1/2 compliant and how to use the additional options to do some available formatting as shown on the screenshots:
What I cannot figure out is how to force it so that:
the #param attribute is followed by two spaces, the argument type, two more spaces, and finally the variable name
effectively giving me:
/**
* Register a binding with the container.
*
* #param string|array $abstract
* #param \Closure|string|null $concrete
* #param bool $shared
* #return void
*/
I can only get it to do the following (please notice single spaces after #param and argument type):
/**
* Register a binding with the container.
*
* #param string|array $abstract
* #param \Closure|string|null $concrete
* #param bool $shared
* #return void
*/
Is there any way of making it re-format the code to this spec?
There is simply no such option currently available.
https://youtrack.jetbrains.com/issue/WI-18408 and related tickets -- watch them (star/vote/comment) to get notified on any progress.
In mean time -- maybe you can use some 3rd party tool that can do such formatting? It can be invoked as External Tool manually (menu or shortcut) or maybe even as an File Watcher (runs on file modification).
Related
With every new CCS-Version, I always search on how to activate documentation with Doxygen.
I think I'm not the only one, so I just wanted to show it to everyone again. (And for me if I have to install a never CCS again)
To use doxygen I am using the eclox-Plugin for eclipse.
The installation ist quite easy and described here https://anb0s.github.io/eclox/
But the tricky part is, how the activate the documentation while coding so that the documentation body for a function will automatically appear if you type /** one line above the function.
Inside CCS you have to go to Window->Preferences, make sure the advanced settings are displayed (button at the bottom). Then go to C/C++->Editor and change the property of the "Documentation tool comments" to Doxygen.
Now you can type /** over a function to automatically generate the documentation body like this.
/**
*
* #param pvData
* #param usLength
* #param ulStatusFlag
* #return
*/
uint16_t IPCLiteLtoRGetResult (void *pvData, uint16_t usLength, uint32_t ulStatusFlag)
Maybe this will help somebody (most likely myself) in the future.
I used to reference methods in Java Doc like this:
/**
* #see com.myapp.view.fragment.PlaybackControlFragment#onPlaybackStateChanged
*/
I don't know how to reference same method in kotlin?
The part com.myapp.view.fragment.PlaybackControlFragment is linked however method name is not clickable and link.
What is the right syntax?
Just change # to . and it will work correctly.
/**
* #see com.myapp.view.fragment.PlaybackControlFragment.onPlaybackStateChanged
*/
is it possible to define something like macros in Doxygen?
I want write a comment something like this:
/**
\return return_self_reference
*/
and Doxygen will replace return_self_reference with a string defined by me.
The comment that would then be read by Doxygen would be this one:
/**
\return A reference to the instance that the operator was called on.
*/
Please note that, alltough I called it a macro earlier, I do not want to define a C macro or anything like that in the actual code.
Doxygen has for these cases the configuration parameter ALIASES.
Lets take the following example:
/** \file
*/
/**
* \return the normal version
*/
int fie0(void);
/**
* \return \str1_repl
*/
int fie1(void);
/**
* \str2_repl
*/
int fie2(void);
and set the following ALIASES in the doxygen configuration file (see also the manual for more possibilities of ALIASES):
ALIASES = "str1_repl=just the text in replacement" \
"str2_repl=\return return and the text in replacement"
and we will get the following result:
When I edit an annotation of method, it shows warning on the annotation line, and it didn't show on the other file which I edit the annotation use the same way.
I wonder how it happened and how to solve this warning.
Add the description:
* #param success description of param here removes warning
With warning:
/**
* #param command
*
* The callback id used when calling back into JavaScript.
*/
Without warning:
/**
* #param command
* The callback id used when calling back into JavaScript.
*/
How do you generate comments for your methods/classes? Simply typing:
/**
And pushing enter does not seem to work in IntelliJ IDEA 2016.1.3
It seems like Dokka has superseded KDoc, but why is there no support in IntelliJ? Or am I missing something?
Clarification: when typing in /** + enter, this gets generated:
/**
*
*/
But I'm wondering why the generation of #param and others aren't added (like IntelliJ does for Java). These annotations are used for documenting Kotlin code as well (https://kotlinlang.org/docs/reference/kotlin-doc.html)
To expand on #yole's answer and #Charles A.'s comment, here is a full explanation of the preferred format when creating KDocs and how it differs from JavaDocs.
The Kotlin documentation here:
https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments
...says:
Generally, avoid using #param and #return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment, and add links to parameters wherever they are mentioned. Use #param and #return only when a lengthy description is required which doesn't fit into the flow of the main text.
Avoid doing this:
/**
* Returns the absolute value of the given number.
* #param number The number to return the absolute value for.
* #return The absolute value.
*/
fun abs(number: Int) = ...
Do this instead:
/**
* Returns the absolute value of the given [number].
*/
fun abs(number: Int) = ...
The #param and other tags are not generated because the recommended documentation style for Kotlin is to refer to parameter names from the doc comment text using the [foo] syntax, rather than to document them using explicit #param tags. You can check the Kotlin standard library documentation to see how this style is used.