So I've searched and found a lot on this topic, but nothing that seems to directly address my question or if it does it either pretty much requires me to basically reimplement my object definition in JSDoc (eg #typedef, which strikes me as duplication of effort and makes two places to maintain 'code') or does it in a way that produces weird documentation (eg, using namespaces).
So if I have a classes with a nested object (say, a dictionary lookup), I can't seem to get its members to appear automagically in JSDoc as part of the class documentation. Instead, they all appear as individual entries in the Global section.
Example:
/**
* An example class
* #class
*/
class MyClass {
/** An object literal */
myObjectLiteral = {
/** property 1, ya know? */
objProperty1: "moo",
/** property 2, baby! */
objProperty2: "goo"
}
}
MyClass appears as a class with myObjectLiteral as a member, but objProperty1 and objProperty2 appear as entries in the Global section.
Is there an elegant way to get JSDoc to include the object literal and its properties in the class documentation? I thought that using #memberof might do the trick, but it didn't seem to work (tho I may have effed up the syntax).
Related
The question may be a bit confusing, and is best illustrated by an example:
unit Test
interface
type
TestClass = class()
Splitter1: TcxSplitter;
procedure SomeMethod();
end;
implementation
uses
cxSplitter;
// Locally-declared child type
type
TcxSplitterAccess = class(TcxSplitter);
procedure TestClass.SomeMethod()
var
pos: integer;
begin
// Access to protected field FPositionBeforeClose by casting
pos := TcxSplitterAccess(Splitter1).FPositionBeforeClose;
end;
Notice in the implementation section that there is a type TcxSplitterAccess being declared as a child of the TcxSplitter class. In the method SomeMethod(), belonging to the class TestClass, a TcxSplitter object is cast to the locally-declared TcxSplitterAccess class, and then a protected field is accessed on that object.
This is surprising to me as someone coming from a background of languages like Java, C++, C#, etc. In those languages, it is possible to access protected data in an object so long as you are doing it from within that object's type or an inherited type. For example, a method inside of a class ClazzA can access the private fields of other ClazzA objects since access is enforced at the type level rather than the instance level. Declaring a class locally in these languages would not give the containing class access to the local class' protected data (edit: As pointed out in the comments, this is actually not true at least for Java).
In this example, however, the type TestClass is directly accessing a protected field on the TcxSplitter object by first casting to the TcxSplitterAccess type. I am having trouble finding documentation on why this "trick" works. Does Delphi handle access levels fundamentally differently to Java-like languages and allows this sort of thing? Regardless, why does this trick work?
While I stumbled onto this behavior by using a nested, inherited class in order to access fields on the parent class (which breaks encapsulation, and I shouldn't do), the use of inheritance here is unnecessary. If the nested class did not inherit from a class, but instead had its own protected fields defined, TestClass would still be able to access those protected fields.
A unit has implicit-friendship semantics within itself. Types declared in the same unit are "friends" of each other (similar to friend in C++), and so can access each other's private and protected members (but not strict private or strict protected members).
So, in this case:
TcxSplitterAccess derives from TcxSplitter, so TcxSplitterAccess inherits all of the protected (but not private) members of TcxSplitter via normal class inheritance.
TestClass is declared in the same unit as TcxSplitterAccess, so TestClass has access to all of the protected members of TcxSplitterAccess, including the protected members of TcxSplitter (and the protected members of its ancestors).
FPositionBeforeClose is protected in TcxSplitter.
So, that is why TestClass.SomeMethod() is able to access FPositionBeforeClose when type-casting the Splitter1 object to TcxSplitterAccess.
This is covered by the Delphi documentation:
Private, Protected, Public, and Published Declarations
Classes and Objects (Delphi): Visibility of Class Members
I noticed today while working on a very small JS file that my defined type wasn't allowing intellisense when a variable was declared later on as being of that type. Turns out that changing the typedef to have a capital letter fixes the issue. My type definition is at the top of the file and the variable that is of that type is within an IIFE.
If I move the type definition inside the IIFE, then it works no matter the case of the type's name. However, leaving the type definition at the top of the file (outside the IIFE) and making the name capitalized also makes it work.
Is it documented anywhere that a capitalized type definition makes it global?
EDIT: Adding a couple screenshots. This seems to be sporadic to reproduce using simple examples.
Non-working
Working
EDIT_2: It seems to be related to having a variable with the exact same name as the type definition.
/**
* An object that stores all the necessary contextual data
* Defined inside the HTML file loaded for the alert
* #typedef {Object} Test
* #prop {Number} personId person_id of the patient
*/
(function() {
/** #type {Test} */
const Test = window.Test;
Test
})();
You should consider the #typedef as being a variable – one that's only usable in your type declarations.
That means that you can override that variable in your local scope, so that it means something else there.
And that's exactly what you are doing here.
I am relatively new to Scala. I have several helper methods and need to place them somewhere. My instinct is to group helper methods in stateless object.
It is concerning however that me or someone else could start adding state to that object with var fields. That will cause side-effects that not only helper methods' arguments but state of the object can influence behavior of methods.
I want to have protection from that for now and need to mark object as not holding (mutable) state so that compiler or some validation tool (e.g. Fortify) would raise an error when someone tries to add state to the object. Is it possible in Scala? Is there some #Immutable or #Stateless annotation?
Example code:
object StreamHelpers /* <-- this needs to be marked immutable or stateless */ {
var something: String = "change me" // <-- this should cause build to fail
def streamToString(stream: InputStream): String = {
managed(new InputStreamReader(stream, StandardCharsets.UTF_8))
.map(reader => CharStreams.toString(reader)).getTry.get
}
// other stuff
}
Update: as per discussion in comments, I am interested to know whether in Scala it is possible to:
disallow adding var-s to an object
OR
disallow adding both val-s and var-s to an object
with keyword or annotation of any sort. Or is it possible to achieve that with macros or meta-programming if Scala does not support it out of the box?
Use WartRemover. There is no built-in check for that (except one which bans all use of var), but it shouldn't be hard to write one (and include mutable collection vals while you are at it). Alternately, if you only want to mark specific objects as immutable, a macro annotation would take basically the same code.
In my application I have few classes with package-protected methods and JavaDoc associated. I have then some other classes in same package with public methods -- in a few situations the public method is nothing more than a "proxy" for the package-protected method -- for these kinds of situation I would love to "inherit" the JavaDoc from the pp method but I don't know how to do
#inheritDoc works for inheritance situations
#see and #link creates a pointer to a class/method documentation
I would like to "copy" the documentation, not to create a link to the other's method doc.
I've been looking for this kind of annotation but I did not find it.
Any idea?
btw: using NetBeans if I create an interface and implement it in a class, even though I did not annotate the class methods with #inheritDoc I can see the interface documentation when using the class methods -- still wondering why!
Thanks,
Carlo
Per the JavaDocs documentation, this is only possible in three cases:-
When a method in a class overrides a method in a superclass
When a method in an interface overrides a method in a superinterface
When a method in a class implements a method in an interface
Given that you're not overriding a method, it seems it's not possible.
See here: Automatic re-use of method comments
Using a Behat sub-context class I need to call a method from the main context, e.g. $this->getMainContext()->fooBar(). PhpStorm quite reasonably warns me that fooBar() doesn't exist, because it expects getMainContext() to return an ExtendedContextInterface, not my concrete FeatureContext.
Is there a way to annotate my sub-class to tell PhpStorm that getMainContext() actually returns my concrete class?
One solution is to override getMainContext() just to have a method on which to add my own PHPDoc, thus specifying a different return type, but adding a method just to get nicer code sense in an IDE is horrid.
BTW, I know this is all a bit hacky and that theoretically my sub-context shouldn't depend upon my main context having a particular concrete implementation; in reality though Behat doesn't make that practical.
Using the standard #method annotation for the class works:
/**
* #method FeatureContext getMainContext()
*/
class SubContext extends BehatContext
{
public function foo()
{
$this->getMainContext()->bar();
}
}