I woul like to reference method's parameters in the documentation text,
but have no idea how to do it.
In .NET world we use tag paramref
Just as an example:
/** Send email with the specified #paramref body to the addesses given in #paramref to.
#param body Just a plain text or teamplate-aware text.*/
def SendEmail(body: EmailBody, to: EmailAddress*) = ???
How is it done in Scala?
You can make reference in Scaladoc similarly to Javadoc. According to the documentation for javadocs:
{#code foo}
and
<code>foo</code>
But XML looks ugly and not readable, prefer to use {#code foo} instead.
I think you should find everything you need in https://docs.scala-lang.org/style/scaladoc.html. Do a string search for "param name".
Related
We have a container object for our custom classes, but JSDoc doesn't seem to like my notation for these types and comments them with
"invalid type syntax".
I am using PHP-Storm.
My JSDoc is according to this principle:
/** #type {Container['3rd'].className} */
When I change the annotation to this it seems to be valid since the comment disappears:
/** #type {Container.3rd.className} */
Why is the first property accessor syntax not considered valid in JSDoc?
The accessor using brackets is valid otherwise in Javascript code so why not in jsdoc annotations?
JSDocs #type notation is not a JavaScript expression. It is a JSDoc Namepath Expression.
If you look into these 2 links in detail you'll see a few things;
There are valid namepaths that would not be valid js:
MyConstructor#instanceMember
MyConstructor~innerMember
There are valid #type expressions that use non-JS syntax:
/** #type {(string|Array)} */
There are no mentions of using Bracket notation in either of these docs (for types/namespaces).
I've seen code snippets like these:
export interface IUser {
email?: string;
firstName?: string;
lastName?: string;
}
But why are the variable names suffixed by a question mark? This snippet is part of an example of using mongodb with Typescript.
The answer is probably somewhere out there but I seem to be using the wrong keywords since I can't find it.
In TypeScript, <name>?: <typename> a shorthand for <name>: <typename> | undefined.
This indicates to the type system that a symbol may contain a value of the indicated type or it may contain the value undefined (which is like null).
This is important when the (new in TypeScript 2) --strictNullChecks option is enabled. The documentation on Null- and undefined-aware types option is probably where you should start to understand why this is useful.
It means they can be there but dont have to be. It allows for optional field names. It can be quite common to use.
An example use is allowing users on a website to have an optional display name.
If I am not mistaked, its to indicate that its optional, that means that it can be null.
I am looking at CodeMirror help and registerHelper is described as
CodeMirror.registerHelper(type: string, name: string, value: helper)
Registers a helper value with the given name in the given namespace
(type). This is used to define functionality that may be looked up by
mode. ...
http://codemirror.net/doc/manual.html#registerHelper
This does not explain what the value is, when is it called (it seems to be a function), or why getHelpers accepts a position.
Is helper similar to a mode, but providing non-visual annotations (for code lookups)?
It's just a value -- any value. How it will be used depends on the type of helper. For "hint", it'll be a function providing completions at a given point in a document, for "hintWords", it'll be an array of strings that form possible completions, for "wordChars", it is a regular expression describing the characters that count as word characters for a mode, and so on.
Studying Lift I've immediately found a non-familiar #> operator. What exactly does it mean?
Example:
/**
* Put the messages in the li elements and clear
* any elements that have the clearable class.
*/
def render = "li *" #> msgs & ClearClearable
I can read the comment to know what's the line for, but am not sure about the code mechanics here.
The operator #> is used to create CSS Selector Transformers.
You provide a CSS selector as a string and then apply it to the given argument which can be a sequence, a string or a NodeSeq and get a function of type NodeSeq => NodeSeq that applies the transformations. The & is used to chain those transformations.
There is no operator in Scala, and hence, there is no #> operator.
What looks like an operator is a method, and if it is a method, it isn't in Scala but in a class. On Smalltalk, you would say, that you can send the object a #> - message.
Since the object on the right is a String, and String does not have a #>-message, there must be an implicit in scope, which takes a String, and transforms it into an object, which has such a method.
Implicits are only searched for in the code itself or directly imported code, not in code imported from imported code, so it shouldn't be too much work, to search for #>. Maybe your IDE can tell you, where it is defined.
At my work we use a typical heavy enterprise stack of Hibernate, Spring, and JSF to handle our application, but after learning Scala I've wanted to try to replicate much of our functionality within a more minimal Scala stack (Squeryl, Scalatra, Scalate) to see if I can decrease code and improve performance (an Achilles heal for us right now).
Often my way of doing things is influenced by our previous stack, so I'm open to advice on a way of doing things that are closer to Scala paradigms. However, I've chosen some of what I do based on previous paradigms we have in the Java code base so that other team members will hopefully be more receptive to the work I'm doing. But here is my question:
We have a domain class like so:
class Person(var firstName: String, var lastName: String)
Within a jade template I make a call like:
.section
- view(fields)
The backing class has a list of fields like so:
class PersonBean(val person: Person) {
val fields: Fields = Fields(person,
List(
Text(person.firstName),
Text(person.lastName)
))
}
Fields has a base object (person) and a list of Field objects. Its template prints all its fields templates. Text extends Field and its Jade template is supposed to print:
<label for="person:firstName">#{label}</label>: <input type="text" id="person:firstName" value="#{value}" />
Now the #{value} is simply a call to person.firstName. However, to find out the label I reference a ResourceBundle and need to produce a string key. I was thinking of using a naming convention like:
person.firstName.field=First Name
So the problem then becomes, how can I within the Text class (or parent Field class) discover what the parameter being passed in is? Is there a way I can pass in person.firstName and find that it is calling firstName on class Person? And finally, am I going about this completely wrong?
If you want to take a walk on the wild side, there's a (hidden) API in Scala that allows you to grab the syntax tree for a thunk of code - at runtime.
This incantation goes something like:
scala.reflect.Code.lift(f).tree
This should contain all the information you need, and then some, but you'll have your work cut out interpreting the output.
You can also read a bit more on the subject here: Can I get AST from live scala code?
Be warned though... It's rightly classified as experimental, do this at your own risk!
You can never do this anywhere from within Java, so I'm not wholly clear as to how you are just following the idiom you are used to. The obvious reason that this is not possible is that Java is pass-by-value. So in:
public void foo(String s) { ... }
There is no sense that the parameter s is anything other than what it is. It is not person.firstName just because you called foo like:
foo(person.firstName);
Because person.firstName and s are completely separate references!
What you could do is replacing the fields (e.g. firstname) with actual objects, which have a name attribute.
I did something similiar in a recent blog post:http://blog.schauderhaft.de/2011/05/01/binding-scala-objects-to-swing-components/
The property doesn't have a name property (yet), but it is a full object but is still just as easy to use as a field.
I would not be very surprised if the following is complete nonsense:
Make the parameter type of type A that gets passed in not A but Context[A]
create an implicit that turns any A into a Context[A] and while doing so captures the value of the parameter in a call-by-name parameter
then use reflection to inspect the call-by-name parameter that gets passed in
For this to work, you'd need very specific knowledge of how stuff gets turned into call-by-name functions; and how to extract the information you want (if it's present at all).