Describe a Method`s Input Parameters and Output Type exactly

Thread is closed for posting
47 posts, 2 answers
  1. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 17 Mar 2013 Link to this post

    When reading the documentation I rather often do not know, what datatypes are expected as parameters or which datatype is returned from a method call. I appreciated, if these details were given in the documentation.

    Let me make an example. Look at TreeView expand method. The parameter is described as "nodes Selector". What does this mean? Is it a jQuery selector such as "#tree" or "div.tree"? Or is this an DOM object or maybe a jQuery object? The samples show that probably both a selector or a DOM object can be given to the method. If this is so, I would like to read it in the documentation.

    A user might also try to find out about method parameters by looking at the TypeScript definition. There he will find...
    class TreeView extends kendo.ui.Widget {
        expand(nodes: string): void;
    }
    Probably this is not correct, as the samples show that also a DOM object can be expanded.

    Michael G. Schneider
  2. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 18 Mar 2013 Link to this post

    Hello Michael,

    The parameter of the expand/collapse method can be a string, a DOM element, or a jQuery object, because it is internally wrapped in a jQuery object (roughly, parameter = $(parameter)). The documentation will be updated shortly with the proper signature, and the TypeScript definitions have been patched, as noted in the other thread you started.

    Regards,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  3. Kendo UI is VS 2017 Ready
  4. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 20 Mar 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer,

    Michael G. Schneiderf
  5. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 21 Mar 2013 Link to this post

    Hello Alex,

    please look at TreeView.parent.
    • The parameter is described as "Element". As the sample shows, it can also be a "jQuery".
    • Moreover, from reading the documentation how can I know what comes back? Is it a DOM Element or is it a jQuery Element?
    The parameters and the return type should be described exactly. I would really appreciate that. It is rather difficult, to find out by trying. Especially the return types are mostly not well described.

    Looking at the TypeScript definition is no real help. Neither the parameter nor the return type seems to be correct.
    class TreeView extends kendo.ui.Widget {
        parent(node: Element): void;
    }
    When seing such problems in the documentation, what should be done? Will these shortcomings be addressed in a service pack on a global basis? Or is it reasonable to create entries here in the forum?

    Michael G. Schneider
  6. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 22 Mar 2013 Link to this post

    Hello Michael,

    There have been some discrepancies in the API documentation of the TreeView, which we now fixed. Element always denotes a DOM element, and jQuery denotes a jQuery object. Such shortcomings in the TypeScript will be addressed with each internal build -- but we appreciate every feedback we get, so you are encouraged to let us know if you stumble upon such problems. Your Telerik points have been updated for this bug report.

    Regards,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  7. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 27 Mar 2013 Link to this post

    Hello Alex,

    if a method has several signatures, e.g. accepting a "selector string" or a "DOM element" or a "jQuery element", I suggest you do not describe the parameter as "any", but you use overloading instead.

    Intellisense would greatly benefit from it.

    Michael G. Schneider
  8. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 27 Mar 2013 Link to this post

    Hello Michael,

    Thank you for the feedback. Because implementing this requires a non-trivial effort, we have logged it and will consider it for future releases.

    Regards,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  9. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 27 Mar 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer and the points. You might include overloading widget by widget. It need not be done all at once.

    Out of curiosity: how do you create the definition file? Is it written by hand? Do you generate it out of some database, containing all classes and methods? Maybe by scanning the comments in the source code?

    Michael G. Schneider
  10. Answer
    Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 27 Mar 2013 Link to this post

    Hello Michael,

    Some of the file is written by hand; most of the definitions are generated from the public API. The methods in question are generated, and creating all correct signatures is the non-trivial task that I mentioned (i.e. taking into account the different types, as well as optional parameters).

    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  11. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 28 Mar 2013 Link to this post

    Hello Alex,

    the following definitions are missing

    • kendo.Class
    • kendo.Observable inheriting from kendo.Class
    • kendo.ui.plugin
    • DataSource.create

     Michael G. Schneider
  12. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 01 Apr 2013 Link to this post

    Hello Michael,

    We have added the Class class, as well as the inheritance. Both the kendo.ui.plugin and the DataSource.create methods are not documented and will not be added to the TypeScript definitions until they are.

    Regards,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  13. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 01 Apr 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer. Would you please elaborate on...
    • You say that you included the "Class" and the inheritance. Where can I download that file? Or is it for internal use only? I very much appreciated, if the file were always available in its most recent version.
    • I do not understand this "not documented" statement. At least kendo.ui.plugin is documented (please see kendo.ui.plugin).
    • Aren't those two methods officially supported? Shouldn't they be used? After all, they are needed for plugin development.
    Michael G. Schneider
  14. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 02 Apr 2013 Link to this post

    Hello Michael,

    I am sorry to have mislead you. Both methods are documented, and have been added to the attached TS file.

    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  15. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 02 Apr 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer and the definition file.

    One more suggestion: the static method DataSource.create is mentioned in blog entries. However, it is not documented in API Reference. At least, I never saw it somewhere.

    Michael G. Schneider

  16. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 02 Apr 2013 Link to this post

    Hello Michael,

    Yes, that mislead me that it is not documented. It can be found in both blog posts and the getting started help topic; it will be documented shortly.

    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  17. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 06 Apr 2013 Link to this post

    Hello Alex,

    the methods "static fn" and "static extend" should be added to "kendo.Observable" and "kendo.ui.Widget".

    I am not sure whether the static methods should automatically be inherited into the two classes per Typescript language definition. Anyway, in reality they are not inherited. Including the definitions into Observable and Widget fixes this.

    Even if inheriting the static methods would work, the return type should not be "Object". Calling "init" on "fn" is impossible that way.

    Moreover, the options parameter in the Kendo.View's constructor is missing.

    Michael G. Schneider
  18. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 10 Apr 2013 Link to this post

    Hello Michael,

    Indeed, static members are not inherited in TypeScript. I'm attaching the latest TS definitions.

    Greetings,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  19. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 10 Apr 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer and the definition file. I looked at the options for the kendo.View constructor.
    • It has several properties (e.g. title, reload, defaultTransition, etc.) which are not described in the documentation.
    • The documentation describes the properties "tagName" and "wrap", which are not part of the ViewOptions interface.
    Maybe the additional properties in the interface do not belong there. Probably, they are from mobile. However, "tagName" and "wrap" should be listed in the interface.

    Moreover, the kendo.View constructor has an "Element" parameter in this definition file. However, a string can be passed as the first parameter.

    Moreover, calling "widget.fn.init" is not possible. Method "init" is missing.

    Moreover, using keno.ui.plugin is not possible due to its first parameter "widget: Function". Type 'Widget' is missing property 'prototype' from type 'Function'.

    Michael G. Schneider

  20. Answer
    Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 12 Apr 2013 Link to this post

    Hello Michael,

    Thank you for your feedback. You can find attached the updated definitions file.

    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  21. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 12 Apr 2013 Link to this post

    Hello Alex,

    thanks a lot. I did a quick check and all problems were gone.

    Michael G. Schneider
  22. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 15 Apr 2013 Link to this post

    Hello Alex,

    • kendo.ui.ListViewOptions.selectable isn't a string, it is a bool
    • kendo.ui.GridViewOptions.selectable is declared as any, but might be declared bool
    Michael G. Schneider
  23. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 16 Apr 2013 Link to this post

    Hello Michael,

    The Grid selectable option can be either a bool or a string ("multiple, row"). The same is valid for the ListView selectable option, so both need to be of any type. The attached definitions address this.

    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  24. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 16 May 2013 Link to this post

    Hello Alex,
    • kendo.ui.WindowOptions.height currently is a "number", shouldn't that be "string" or even "any"
    • same for maxHeight, minHeight, width, ...
    • kendo.fx seems to be missing
    • shouldn't kendo.ui.WindowAnimationClose contain a "reverse"
    • same for WindowAnimationOpen
    Regarding the WindowOptions's height/width, the API Reference also describes these parameters as "Number".

    Regarding WindowAnimationClose, the API Reference does not mention a "reverse".

    Michael G. Schneider
  25. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 18 May 2013 Link to this post

    Hello Michael,

    • kendo.ui.WindowOptions.height currently is a "number", shouldn't that be "string" or even "any", same for maxHeight, minHeight, width, ...
      This is valid for width and height. The min/maxWidth/Height support only pixel values (i.e. numbers).
    • kendo.fx seems to be missing
      Added.
    • shouldn't kendo.ui.WindowAnimationClose/Open contain a "reverse"
      Added.
    All the best,
    Alex Gyoshev
    the Telerik team
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  26. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 13 Jun 2013 Link to this post

    Hello Alex,

    the following seems to be missing.
    • kendo.data.binders
    • kendo.data.Binder.extend
    • kendo.data.Binder.fn
    Michael G. Schneider
  27. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 13 Jun 2013 Link to this post

    Hello Alex,

    the following seems to be missing.

    kendo.data.binders
    kendo.data.Binder.extend
    kendo.data.Binder.fn

    P.S.: I initally created this post with an unordered list. When trying to post, the message "Invalid post content" appeared in red under the input  textarea.

    P.S.P.S.: Yesterday the previous post with the bulleted list was not shown. It appeared today.

    Michael G. Schneider
  28. Alex Gyoshev
    Admin
    Alex Gyoshev avatar
    2500 posts

    Posted 17 Jun 2013 Link to this post

    Hello Michael,

    Thanks for reporting these -- they have been added.

    Regards,
    Alex Gyoshev
    Telerik
    Join us on our journey to create the world's most complete HTML 5 UI Framework - download Kendo UI now!
  29. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 17 Jun 2013 Link to this post

    Hello Alex,

    thanks a lot for the answer. Maybe I am doing something wrong. I also reported...

    kendo.data.Binder.extend
    kendo.data.Binder.fn

    Shouldn't they also be inserted into the file?

    Michael G. Schneider


    P.S.: Once again the "invalid post content" message appeared, when I posted this text with a bulleted list. Is this a problem on my side or is it a general problem with the forum?
  30. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 17 Jun 2013 Link to this post

    It is impossible to post reliably, "invalid post content" is given.
  31. mgs
    mgs avatar
    163 posts
    Member since:
    Jan 2011

    Posted 17 Jun 2013 Link to this post

    Post may not contain bullets, must be short
Back to Top
Kendo UI is VS 2017 Ready