To link another class, I can use [[package.Classname]].
Linking functions defined by def works as well, but trying to link variables doesn't work.
What I've tried:
object Foo {
val BAR = 0
}
object Example {
/**
* Does the thing with [[Foo.BAR]]
*/
def doTheThing(): Unit = {
}
}
I've also tried [[Foo#BAR]] (from another post) instead of [[Foo.BAR]], which fails as well.
What's the proper way to link variables in scaladoc?
The right way to go is what you have already tried:
/**
* Does the thing with [[Foo.BAR]]
*/
Please note that if this is just an example to a more complicated scenario, you need to include the whole package path of Foo.BAR. For example, if Foo is under:
package a.b.c.d
Then you need to do:
/**
* Does the thing with [[a.b.c.d.Foo.BAR]]
*/
You can find in the scaladocs docs:
Create links to referenced Scala Library classes using the square-bracket syntax, e.g. [[scala.Option]]
For more information you can read SCALADOC FOR LIBRARY AUTHORS
You can see here and example how the akka library is using it.
Related
I have a project which contains several interface to other programs. These interfaces are defined as classes and spread out over the project.
I wonder whether it is possible that I can set a marker in the class description and doxygen later generates a list of links to all the markers.
e.g:
/** \marker interface **/
class Interface_01
{
}
/** \marker interface **/
class Interface_02
{
}
In a different doxygen file:
\listmarker interface
Which should then lead to something like this in the output:
* Interface_01
* Interface_02
This problem looks a bit like a problem for \xrefitem.
In the documentation:
the paragraph Aliases with arguments (http://doxygen.nl/manual/custcmd.html#custcmd_complex).
the command \xrefitem (http://doxygen.nl/manual/commands.html#cmdxrefitem)
#groupname tags are not getting identified in the documentation for Scala. I am using Intellij IDE for creating the Scala doc.
Using #groupname tag on Scala objects seem to work fine but with class, I ma only finding value members not arranged in groups.
/**
* A class to represent ''All Methods needed for Stdraw Tests''.
* #groupname some_funcs Some Functions
* #constructor Create Some Functions
*/
class xyz{
/**
* #group some_funcs
*/
def something() = {something}
}
When I run this code with Generate Scala doc, i should get something function with heading Some Functions, but I get nothing. I see only the valued members. Even tried adding "scalacOptions in (Compile,doc) := Seq("-groups", "-implicits")" in build.sbt which did nothing. Any one faced this issue.
My question is very simple. How can you create your own tooltip information for your own created methods and classes, the way all methods and classes of the standard library of java have, when you are writing code and choosing methods and subclasses?!
For example, let's say I have a Class A, in which I have a Method B. Now I define a new instance of Class A in another Class C by writing "A my_class = new A()". Now when I write "my_class.B" I want the Eclipse to show me the information about the Method B in a tooltip, so I know what are the parameters I have to pass to that method B.
Here is a picture example:
http://www.subshell.com/en/subshell/blog/eclipse-javadoc-tooltips100~v-full_small.jpg
I searched a while, but I didn't find any solutions for that. So maybe you know how to do that!
In eclipse, once you add the javadoc comment to your method, it will show up wherever you refer to that method. The Javadoc comment takes the form
/**
* This is my method description
* #param x the total number of mangoes allowed
* #return int the number of litres of juice possible
*/
Javadoc comments are placed just before the artifact that it describes. So a method comment will go on the line before the method, a class comment goes on the line before the class statement and so on.
I know it's possible to get IDE autocompletion from the *Table classes in Doctrine by doing things like this:
SomethingTable::getInstance()-><autocomplete>;
But the most important part is missing. I want autocomplete on the model classes themselves, not just the Table classes. It appears that Doctrine is not properly declaring the PHPdoc #return object types in the find and other standard model methods.
For example what I want to be able to do is this:
$something = SomethingTable::getInstance()->find($id);
$something-><autocomplete>
and have that pop up the methods and properties of the Something class.
I should mention too that I don't specifically care about using the SomethingTable::getInstance() syntax at all. ANY decent syntax that's standard Symfony is acceptable. Most of the time I'm fetching objects (or Doctrine_Collections) via custom queries like this:
$somethings = Doctrine_Query::create()
->from('Something s')
->leftJoin('s.SomethingElse s2')
->where(...);
By the way, in case it's not clear, I'm asking if there's any automatic solution to this with ANY of the various Doctrine find, fetch or query syntaxes. I'm NOT asking how to manually edit all the PHPdoc headers to cause the behavior I want.
I'm using NetBeans 6.9.1 and Symfony 1.4.12 with Doctrine, but not everyone working on the same code uses NetBeans.
The problem is that autogenerated *Table classes have the wrong phpdoc #return in the getInstance() method:
/**
* Returns an instance of this class.
*
* #return object MyModelTable
*/
public static function getInstance()
{
return Doctrine_Core::getTable('MyModel');
}
You just need to manually fix the #return line deleting the word "object":
* #return MyModelTable
And magically IDE autocompletion just works, giving you all the instance and static methods:
MyModelable::getInstance()->... //(you'll have autocompletion here)
I know, its a pain to have to manually fix this but at least it only have to be done once for each model *Table file.
In netbeans its quite easy:
$foo = ModelNameTable::getInstance()->find(1); /* #var $foo ModelName */
/* #var $foo ModelName */ tells netbeans to handle the variable $foo as a ModelName class.
just fix the generated model files by adding
/**
* #return ModelNameTable
*/
in the comment of the getInstance() method. This will provide autocomplete for the model file.
Regarding the find method, you can edit the comment of the class like this :
/**
* #method ModelName find()
*/
I think it might be possible for you to do this automatically by creating you own skeleton files.
Or not : Symfony Doctrine skeleton files
You could use sed to achieve this, or perhaps build your own task using the reflection api.
I'm working on Magento templates, but this issue would apply to any template loading system.
As these templates are loaded by the template engine there's no way for the IDE (in this case Aptana) to know what object type $this is.
Potentially it could more than one object as a single template could be loaded by multiple objects, but ignoring this, what would the correct phpdoc syntax be to specify a specific class for the $this object?
You can define it like this:
/* #var $this type */
where type is a class name
To be clear, using $this should only ever indicate an object of the current class, right?
PhpDocumentor doesn't currently (v1.4.3) recognize $this as a specific keyword that should equate to a datatype of the class itself.
Only datatypes known by PHP and classes already parsed by PhpDocumentor are the proper datatype values to use with the #return tag. There is a feature request in to have some option available in PhpDocumtentor to aid in documenting fluent methods that always "return $this". [1]
In the case of the #var tag, I don't see how it would be feasible for a class variable to contain its own class instance. As such, I can't follow what "#var $this" should be saying.
If, however, your intention with $this is not for fluent methods that "return $this", and was simply to be some shortcut to PhpDocumentor and/or your IDE to magically guess what datatypes you might mean by using $this, I'd have to guess there's no way to do it. The closest suggestion I could make would be to use the name of a parent class that is a common parent to all the various child classes that this particular var/return might be at runtime, and then use the description part of the tag to have inline {#link} tags that list out the possible child classes that are possible.
Example: I have a Parent abstract class with Child1, Child2, and Child3 children that each could occur in my runtime Foo class.
So, Foo::_var could be any of those child class types at runtime, but how would I document this?
/**
* #var Parent this could be any child of {#link Parent}, {#link Child1}, {#link Child2}, or {#link Child3}...
*/
protected $_var;
Getting back to the "return $this" issue, I'd document things in a similar way:
/**
* a fluent method (i.e. it returns this class's instance object)
* #return Parent this could be any child of {#link Parent}, {#link Child1}, {#link Child2}, or {#link Child3}...
*/
public function foo() {
return $this;
}
Documenting this way at least allows your class doc to have links to the particular classes. What it fails to do is highlight the fluent 'ness. However, if your IDE is capable of recognizing the class names, then perhaps it will be able to do the necessary logical linking to those other classes. I think Eclipse is able to do this at least with popup help, if you hover over the class name in the tag's description. I do not think Eclipse can use this to then make the various child classes' methods available in code completion. It would know about the Parent methods for code completion, because the datatype I explicitly list is Parent, but that's as far as the IDE can go.
[1] -- http://pear.php.net/bugs/bug.php?id=16223
I have found that defining a type with #var for $this does not work - presumably because $this is special and is treated as such by Aptana. I have a similar need to the poster I think - it is in template files (in my case simply located and included by functions within the data class) that I wish to set a type for $this. As #ashnazg says, setting a type for $this within a class definition is not needed, because the type of $this is always the type of the class (up to inheritance).
There is, however, a workaround for template files. At the top of the template file simply put something like
/**
* #var My_Data_Model_Type
*/
$dataModel = &$this;
Then simply use $dataModel (or whatever you choose to call it - maybe something shorter) instead of $this in the template