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.
Related
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).
I'm trying to document a method and trying to use #link and #code as in JavaDoc.
I know in kotlin there is a kDoc but I can't find them or at least something similar.
#link and #code doesn't exist in kDoc but can easily be replaced by Inline Markup.
from KotlinDoc Linking to Elements
Inline Markup
For inline markup, KDoc uses the regular Markdown syntax, extended to
support a shorthand syntax for linking to other elements in the code.
Linking to Elements
To link to another element (class, method, property or parameter),
simply put its name in square brackets:
Use the method [foo] for this purpose.
If you want to specify a custom
label for the link, use the Markdown reference-style syntax:
Use [this method][foo] for this purpose. You can also use qualified
names in the links. Note that, unlike JavaDoc, qualified names always
use the dot character to separate the components, even before a method
name:
Use [kotlin.reflect.KClass.properties] to enumerate the properties of
the class. Names in links are resolved using the same rules as if the
name was used inside the element being documented. In particular, this
means that if you have imported a name into the current file, you
don't need to fully qualify it when you use it in a KDoc comment.
Note that KDoc does not have any syntax for resolving overloaded
members in links. Since the Kotlin documentation generation tool puts
the documentation for all overloads of a function on the same page,
identifying a specific overloaded function is not required for the
link to work.
For {#link SomeClass} in Java maps to [SomeClass] in Kotlin
For {#code true} in Java maps to `true` in Kotlin
You can write your code with java and convert class into Kotlin.
/**
* #see link
*/
public class Some {
}
will be converted to
/**
* #see [link](http://somelink.com)
*/
class Some
The answer that Artur gave is a good hint in general, but the result is wrong. At least IntelliJ IDEA does not grok the result. The markdown link format using []() is fine in the main comment text, but not for external links in the #see tag. For those, you need the same syntax as in Java:
/**
* Do something.
*
* #see External links in kdoc
*/
I struggled with this for a bit with Android Studio 3.5.2 on Mac. This worked for me:
/**
* [Your fully-qualified class name.function name]
*/
If I didn't use the fully-qualified name Kdoc would complain that it was a unresolved reference. What I couldn't figure out is how to actually use the link itself. For that you need to press and hold the COMMAND key (on Mac) and then the links would be active.
To reference a method use the class:
/**
* When the configuration succeeds **[MyCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
Using a variable/parameter does not work:
/**
* When the configuration succeeds **[myCallback.onConfigured]** is called.
*/
class MyClass(myCallback: MyCallback) {
It seems we should just use a markdown hyperlink without any special tags such as #see or #link:
/**
* This is a doc.
*
* See [this](https://google.com)
* And [this](https://stackoverflow.com)
*/
fun myfun() {}
This doc renders in following way in IDE:
As for the #code you should use Markdown syntax (cause KDoc is an extended version of Markdown):
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.
/**
* Some code sample:
*
* Set<String> s;
* System.out.println(s);
*/
class Scratch
Sample how to leave links for classes:
/**
* [YourClass] Methods
* */
also with method calls
/**
* [YourClass.someMothod] Methods
* */
Real example:
/**
* [BaseActivity] Methods
* */
override fun initVars() {
//Just Sample
}
/**
* [MainContract.View] - Overrides
* */
override fun handleConnectionMassage(isShow: Boolean) {
//Just Sample
}
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.
The double_metaphone() function is defined in a PECL extension and as such PHPStorm cannot see it being defined. I wouldn't like to see any warnings about this. I assume I could make PHPStorm treat this function call as defined through some kind of annotation but I don't know how to make this happen.
You need what is called "stub files":
Create a .php file and place it anywhere in your project (be it project itself... or as an External Library (Settings | PHP | Include paths) -- it does not matter, as long as PhpStorm can see it in this project).
Add that function definition as it would be done in PHP itself: describe all parameters, return type etc. and just leave the body of the function empty.
The documentation is optional: it's just the more doc you have the more useful it will be for PhpStorm and you: the IDE can warn you about invalid parameter type, incorrect return type usage, suggest variables of appropriate types when using code completion for that function etc.
That's it
That's exactly how ALL known PHP functions/classes/etc are done in PhpStorm in the first place: just Ctrl + Click on any standard function/class/constant and see it yourself.
An example: how standard bin2hex function is defined (back in 2013):
<?php
/**
* (PHP 4, PHP 5)<br/>
* Convert binary data into hexadecimal representation
* #link http://php.net/manual/en/function.bin2hex.php
*
* #param string $str A character.
* #return string the hexadecimal representation of the given string.
*/
function bin2hex ($str) {}
You can see all current PhpStorm stubs (and other helper files that IDE uses for PHP completion) in this official repo: https://github.com/JetBrains/phpstorm-stubs
I have this:
'components'=>array(
'less'=>array(
'class'=>'ext.less.components.LessCompiler',
'forceCompile'=> true, //YII_DEBUG, // indicates whether to force compiling
//'compress'=>false, // indicates whether to compress compiled CSS
//'debug'=>false, // indicates whether to enable compiler debugging mode
'paths'=>array(
'less/style.less'=>'css/style.css',
),
),
If I enable forceCompile my site is extremely slow. I would imagine because it regenerates the css on each page load. My question is around disabling it. If I disable it:
Will any changes I make to style.less not reflect in the browser?
If so, what is the point of Less? Surely it can't actually be used in production then? Or do you disable forceCompile so it only generates it once?
Any clarity on forceCompile would be highly appreciated!
(And yes, I looked all of for a clear explanation... best I could find was this).
First let me tell you what is the point of less:
less is a meta language, so in general terms using less helps you write easily maintainable css, although the "language" used is less syntax. As a common example, you can define variables in less that are compiled to css values according to the other statements in your less file. Or you can use mixins, nesting, inheritance concepts like you would in most other languages that support OOP.
So you write understandable, readable pseudo/meta css code that is converted to actual css upon compilation.
Now the extension:
Even if you disable forceCompile, the changes made in style.less should reflect, because the extension checks if the file was modified (the following lines from LessCompiler.php should convince you about that):
if ($this->forceCompile || $this->hasChanges())
$this->compileAll();
// ...
/**
* Returns whether any of files configured to be compiled has changed.
* #return boolean the result.
*/
protected function hasChanges() {
// ...
$compiled = $this->getLastModified($destination);
// ...
$modified = $this->getLastModified($dir);
// ...
}
/**
* Returns the last modified for a specific path.
* #param string $path the path.
* #return integer the last modified (as a timestamp).
*/
protected function getLastModified($path){
//...
}
So forceCompile will always compile the file(s) you specify in paths, and you should not enable it in production. The hasChanges call should take care of less files that have been modified, and compile them, which as you see above is automatically done by the extension.