Resolve signature from name, parameters and return type values

[feloy]

For the moment, the signatures of the operators are defined as simple strings, but these signatures could be resolved from other information:

• name filed,
• parameters field
• a (missing) return type field.

This way, we could be able to display the signatures in a more friendly and adaptable way.

For example:

export const combineAll: OperatorDoc = {
  name: 'combineAll',
  operatorType: 'combination',
  parameters: [
    {
      name: 'project',
      type: 'function',
      optional: true,
      description: `An optional function to map the most recent values from each inner Observable into a new result.
      Takes each of the most recent values from each collected inner Observable as arguments, in order.`
    }
  ],
  returnType: 'Observable',
 ...
}

contains all the necessary information to write:

combineAll(project?: function): Observable

or, if one prefer:

combineAll(
  project?: function // An optional function to map the most recent values from each inner Observable into a new result.
): Observable

[mustafamg]

I support this as the return type is important and missed from the documentation unless the return type is 100% observable objects.
For the optional parameters, I support that as well and have a suggestion in this regard. Using a question mark '?' at the end of a parameter may be misinterpreted by developers of other languages such as Ruby developers. For example, ruby developers understand a question mark at the end of the methods to be a boolean method.

I think surrounding an optional parameter with square brackets [ ] may be more convenient.

[feloy]

I propose this notation for optional parameters as it is the one used in Typescript:

https://www.typescriptlang.org/docs/handbook/functions.html (see Optional and Default Parameters paragraph)

[feloy]

In fact, we could adapt the display of the signature depending on the choice of the user to see it in Javascript or Typescript.

[btroncone]

The return type will always be Observable for operators, unless there is something I'm missing?

[feloy]

The partition operator for example does not return an Observable but a pair.

[ashwin-sureshkumar]

@feloy The return is an observable sequence of pair. The return is still an observable.

[mustafamg]

We have obsarvable, obsarvable, [obsarvable, observable] as a return. They are not the same. I think developers are interested to know the type of output they expected.
For the optional parameter. Using question mark in typescript is not a naming convention, it is a keyword that guides the compiler to consider this parameter optional. Adding this parameter at the end of the optional parameter in documentation will interfere with the actual function implementation. Functions may have defaults, which are optional but without question mark.