New API doc - typos and questions

Re: New API doc - typos and questions

Postby thomthom » Tue Aug 16, 2011 12:26 pm

Dan Rathbun wrote:The same could be true for Community Contributed Sample Code Snippets. Each method could have a collapsed "snippets" section, that works in the same manner.

For an example of what I'm talking about.. see the Sketchup Release Notes page.

Oh, I thought you meant that the release notes had inline comments.
0
Thomas Thomassen — SketchUp Monkey & Coding addict
List of my plugins and link to the CookieWare fund
User avatar
thomthom 
PluginStore Author
PluginStore Author
 

Re: New API doc - typos and questions

Postby Dan Rathbun » Tue Aug 16, 2011 12:45 pm

Since we are on this subject of API page format and features....

The API is still lacking:

  • Fully qualified class names
      The organization of the docs misleads readers in some cases. For instance they would think that the PickHelper and Menu classes (as two examples,) are within the UI namespace. But they are not. They are within the Sketchup namespace.
      Another example is Vertex, the Docs mislead people into thinking it's Geom::Vertex, when it's really Sketchup::Vertex
  • Ancestors: The mixin modules are not displayed for each class.
      It would help greatly if the output of .ancestors().reject{|a|a==self} was displayed for each class and module in the API.
      Code: Select all
      # Class method
      class Module
        def lineage()
          ancestors.reject{|a|a==self}
        end
        def self.lineage()
          ancestors.reject{|a|a==self}
        end
      end
  • Constants
      A constants section is needed for each class and module, to list any constants defined within that namespace.
  • Methods
    • It's not clear (for the API classes,) what are class methods, and what are instance methods. (I suppose we assume they are instance methods.)
    • The access is not specified. (Again we assume they are all public, I suppose.)
0
    I'm not here much anymore. But a PM will fire email notifications.
    User avatar
    Dan Rathbun 
    PluginStore Author
    PluginStore Author
     

    Re: New API doc - typos and questions

    Postby ScottLininger » Tue Aug 16, 2011 4:30 pm

    Dan Rathbun wrote:
    ScottLininger wrote:
    Dan Rathbun wrote:Yea.. but the formatting sucks!


    ...of course if you prefer to post nicely formatted stuff to this thread, that's cool, too! :D

    HOW! ??

    I don't think it takes markup... or does it?
    If so. What kind? git markup? bbCode? what?


    The comments don't accept markup. I'm just saying that if you have a comment that needs code formatting or something, you can post to this Sketchucation thread.

    Thanks for the extra feedback, guys. I've blocked out some time to catch up on the comments.

    Cheers,
    0
    - Scott Lininger
    SketchUp Software Engineer
    Have you visited the Ruby API Docs?
    User avatar
    ScottLininger 
     

    Re: New API doc - typos and questions

    Postby tomot » Sat Aug 20, 2011 1:05 am

    I don't think Scott really gets it!
    The entire API has been written by someone that passed provisionally in middle school. Then went home and proudly displayed his/her proud parents, his/her proficiency in English.
    We used to give a (PP} Provisional Pass to guest students, our government had invited at tax payers expense to receive an education in our country, before they return back to their country of origin. In some cases it was an insult to give our student a PP in line with the PP definition. We also gave most of our guest students a PP, we called it a Political Pass.

    Picking at random:

    Code: Select all
    Group.split

        The split method is used to compute the boolean split (map overlay) of the two groups representing manifold solid volumes (this ^ arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.


    Sorry! but I don't know what this entire CODE statement means:

    what is a boolean split ? (this should be underlined to a definition link)
    what is a manifold solid? (this should be underlined to a definition link)
    what does this mean "If the specified objects (this and arg)"
    where is the (map overlay)?

    Speaking of overlays: the API contains not one 3d image ................" a picture is worth a thousand words"
    Many of the coded API examples, will give errors when entered into the Ruby console.
    I think there is work major work still to be done!

    Speaking of Work to be done:

    There is handful of users at this forum that would probably love to make correction to the API.
    The time it took for them to make comments could have been more productively used to corrected the API.
    Why not give them access to the API server and allow them to make corrections directly?

    cheers!
    0

    tomot 
    PluginStore Author
    PluginStore Author
     

    Re: New API doc - typos and questions

    Postby Dan Rathbun » Sat Aug 20, 2011 3:47 am

    tomot wrote:what does this mean "If the specified objects (this and arg)"

    We've already noted that these terms are confusing. The keyword this is from Javascript, and means the receiver. (It's not a Ruby keyword. It just shows the writer had a brain-fart and his web programming mind spit out the wrong word.)

    Whenever you see this in the API docs, you should replace it with the Ruby keyword self, which is the current instance object, (the object on the left of the 'dot', in this case a group object.) The argument (nicked named "arg") is also a group object.

    .. so to paraphrase:

    self_group.split( arg_group )
    0
      I'm not here much anymore. But a PM will fire email notifications.
      User avatar
      Dan Rathbun 
      PluginStore Author
      PluginStore Author
       

      Re: New API doc - typos and questions

      Postby Dan Rathbun » Sat Aug 20, 2011 3:55 am

      As for the other 3D geometric terms, you'll just have to open another browser to wikipedia, and paste them in.

      The API docs are a technical reference, not a tutorial. It might be nice to have definition links, but we'd rather the errors were corrected first.

      I'm sure you can find a browser plugin that lets you highlight text, then right-click and have a wiki lookup link on the popup menu.

      I'm using Chrome now, and when I hilight "manifold solid" in your post, and right-click, an option appears on the context menu that says: "Search Google for 'manifold solid'"
      It's likely I can find a Chrome extension, that will search Wikipedia, also.
      0
        I'm not here much anymore. But a PM will fire email notifications.
        User avatar
        Dan Rathbun 
        PluginStore Author
        PluginStore Author
         

        Re: New API doc - typos and questions

        Postby TIG » Sat Aug 20, 2011 10:24 am

        To clarify the issue on group1.split(group2) [translated a little] in the Group API notes... there are equally confusing notes for ComponentInstance instance1.split(instance2)[again translated a little]...

        In fact a manifold ['solid'] group can 'split' with another manifold group OR a manifold component-instance - therefore the notes are plan wrong!
        The 'argument' can be a group OR an instance.

        The result is always three*** new groups - one is the intersected 'volume' and the other two are the remains of the group and the 'argument' [group or instance], the originals all deleted. The intersected volume is named 'Intersection', what's left of the group is named 'Difference1' and the group of what's left or the 'argument' is called 'Difference2'. If successful the method returns an array of these groups, the API says they are listed in that order: HOWEVER, in testing the array is in reverse order! i.e. [Difference2, Difference1, Intersection].
        ***Somewhat perversely if the group is wholly inside the 'argument' group/instance then the result is exactly the same two volumes you started with, but they are now recast as the new groups called 'Difference1' and 'Difference2', and although there is an 'Intersection' group made and returned in the array it contains no geometry at all [i.e. (group1.split(group2))[2].entities[0]==nil] - so it might have been better to return 'nil' instead of an array [just as it does if there's a non-manifold object passed] as there was NO real 'split' at all and the originals would then be left unchanged ? If a valid 'Instance' isn't made in code [i.e. not ...entities[0]] then you could undo the 'split' if you don't want to change the two originals - however, be aware that the undo will change the references to the originals, and these will no longer be valid, so you'll need to dig further back again to re-get the references if you want to reuse them ??
        These newly made groups do reuse the two original objects material[s] and apply them logically to the 'Intersection' group as its faces' materials; however, if an original object had default materials to some faces and a material applied to the group/instance itself, then the equivalent new group [like 'Difference1'] will not replicate this; rather, the equivalent faces that had the default material will now have the group.material, the new group will have the default material, and any new 'additional' faces made during the split-operation have the default material too...
        These new groups also ignore the two originals' layers, with all three new groups being always on Layer0 - so if the originals are layered and you want to keep this you'll need to get references to those before they are deleted and apply the layer to.
        Attributes belonging to the originals are also not replicated in the 'Difference' groups...

        In a very similar way an instance can 'split' using a group OR other instance, and it returns the equivalent three groups array etc...

        Other 'boolean' operations for group/component-instance have equal poor explanations and return relatively complicated results...
        0
        TIG
        User avatar
        TIG 
        Global Moderator
         

        Re: New API doc - typos and questions

        Postby tomot » Tue Aug 23, 2011 9:09 pm

        Dan Rathbun wrote:
        self_group.split( arg_group )


        Dan you raise an interesting issue:

        A good technical doc still needs to have a highlighted or underlined link, if the common English language idiom, or word, used could be taken out of context with respect to a specific computer language interpretation. Your self_group.split( arg_group ) example should qualify for such a link.
        0

        tomot 
        PluginStore Author
        PluginStore Author
         

        Re: New API doc - typos and questions

        Postby Dan Rathbun » Tue Aug 23, 2011 9:29 pm

        I don't understand... I am saying it's a typographical eror, and should NOT say "this" at all, it should say "self" instead.

        Anyway.. the current API documentation system stinks, and we've complained about it for years. It seems to be a low priority for Google. (Otherwise they would have hired someone who is a API documentation guru to clean up the mess.)

        IMHO it is an embarrassment for Google (as a company,) knowing the quality that they can produce for other API documentation (from other Google divisions.)
        0
          I'm not here much anymore. But a PM will fire email notifications.
          User avatar
          Dan Rathbun 
          PluginStore Author
          PluginStore Author
           

          Re: New API doc - typos and questions

          Postby Dan Rathbun » Tue Aug 23, 2011 9:41 pm

          tomot wrote:A good technical doc still needs to have a highlighted or underlined link, if the common English language idiom, or word, used could be taken out of context with respect to a specific computer language interpretation.

          OK, maybe I do understand.. it's like what we do here in the forum, when we use a Ruby keyword or classname, we highlight it using the "ruby" button on the edit message toolbar. (Just like I did in the post above, when I highlighted the keyword self.

          Yes I think we agree with that... keyword higlites would make the API much more understandable.
          0
            I'm not here much anymore. But a PM will fire email notifications.
            User avatar
            Dan Rathbun 
            PluginStore Author
            PluginStore Author
             

            Re: New API doc - typos and questions

            Postby brian_concannon » Sun Feb 05, 2012 7:56 pm

            Can you please send me Win32API.rb? It is difficult to find a place to download it, believe it or not...

            Thanks in advance.
            0

            brian_concannon 
             

            Re: New API doc - typos and questions

            Postby TIG » Sun Feb 05, 2012 8:09 pm

            Brian

            Please learn to use the forum's search function [top right]...
            viewtopic.php?p=380121#p380121
            :roll:
            0
            TIG
            User avatar
            TIG 
            Global Moderator
             

            Re: New API doc - typos and questions

            Postby rvs1977 » Tue Mar 13, 2012 8:58 pm

            Hi!

            Under Quick References --> Method Index it will only load from "Symbol, A, B, C, D to E"... not any further.

            I have the same problem in I.E. and Chrome... for more than a week now.
            0

            rvs1977 
             

            Re: New API doc - typos and questions

            Postby Dan Rathbun » Tue Mar 13, 2012 9:47 pm

            All letter links (targets,) work fine for me using Chrome.

            Try clearing your browser cache ??
            0
              I'm not here much anymore. But a PM will fire email notifications.
              User avatar
              Dan Rathbun 
              PluginStore Author
              PluginStore Author
               

              Re: New API doc - typos and questions

              Postby rvs1977 » Thu Mar 15, 2012 5:47 pm

              Hmm... found a solution.

              When I press Methods Index in the menu it opens "https://developers.google.com/sketchup/docs/methods?hl=da"

              I tried to delete ?hl=da so it only said: "https://developers.google.com/sketchup/docs/methods"

              Then it works.
              0

              rvs1977 
               

              Re: New API doc - typos and questions

              Postby Dan Rathbun » Thu Mar 15, 2012 10:49 pm

              rvs1977 wrote:Hmm... found a solution.

              I tried to delete ?hl=da so it only said: "https://developers.google.com/sketchup/docs/methods"

              Then it works.

              On the Google Developers site.. at the lower right, on the bottom (dark gray) toolbar, is a language change button.
              dev_google_lang_button.png

              Use it to switch to English ... then bookmark the page.

              I also posted a API links menu that I exported out of Chrome, ...
              Get it here: SUAPI_Links.zip
              0
                I'm not here much anymore. But a PM will fire email notifications.
                User avatar
                Dan Rathbun 
                PluginStore Author
                PluginStore Author
                 

                "NamedOptions" OptionsProvider bugged?

                Postby Dan Rathbun » Thu Mar 15, 2012 11:16 pm

                  "NamedOptions" OptionsProvider bugged?

                  I am not sure what the intended behavior of the "NamedOptions" OptionsProvider is... so...

                  I'll just describe the weirdness of it, that I see on the PC:

                  1) It is within the Model options scope, ie, accessed via: Sketchup.active_model.options["NamedOptions"]

                  2) It is saved with the model file.

                  3) But once this OptionsProvider is used within a session, all attributes remain loaded, regardless of whether the model is closed, another model opened, or just a new model opened.
                  • An attribute of the same name, from the next file, will overwrite.
                  • But existing attributes will remain unchanged.
                  • If you save the second model, whether you add any attributes, or not, ALL the "NamedOptions" attributes are written into ALL subsequent model files saved during that session.

                  So.. if you happened to open a file, just to view it,... and it had any "NamedOptions" attributes saved,.. and then you started a new model, or re-opened another file for editing... the "NamedOptions" attributes from the "viewed" file, will propagate into your "edit" model (likely without you knowing it.)

                  It does not seem to be desirable behavior. I think there is a bug, in that Sketchup should clear and reset the "NamedOptions" provider when another file is loaded.

                  I wonder what the behavior is on the Mac when multiple files are open ??
                  0
                    I'm not here much anymore. But a PM will fire email notifications.
                    User avatar
                    Dan Rathbun 
                    PluginStore Author
                    PluginStore Author
                     

                    Re: New API doc - typos and questions

                    Postby Burkhard » Wed Sep 05, 2012 12:39 pm

                    I could not find a send_action value for Display or toggle the Measurement Toolbar. Just VCB hide / unhide with Statusbar.
                    Is there an undocumented Value?
                    0
                    User avatar
                    Burkhard 
                    Premium Member
                    Premium Member
                     

                    Re: New API doc - typos and questions

                    Postby TIG » Wed Sep 05, 2012 12:41 pm

                    There's a massive list of numerical PC only codes that do more than the PC/MAC Sketchup.send_action("text") versions... I've PM'd you it...
                    0
                    TIG
                    User avatar
                    TIG 
                    Global Moderator
                     

                    Re: New API doc - typos and questions

                    Postby Burkhard » Wed Sep 05, 2012 12:47 pm

                    You refer to the API list? https://developers.google.com/sketchup/ ... end_action
                    There I could not find what I`m looking for. So my question for undocumented numbers.
                    0
                    User avatar
                    Burkhard 
                    Premium Member
                    Premium Member
                     

                    Re: New API doc - typos and questions

                    Postby renderiza » Tue Sep 25, 2012 9:36 am

                    thomthom wrote:Animation
                    http://code.google.com/intl/nb/apis/ske ... ation.html

                    The first example on that page:

                    Code: Select all
                         # This is an example of a simple animation that floats the camera up to
                         # a z position of 200". The only required method for an animation is
                         # nextFrame. It is called whenever you need to show the next frame of
                         # the animation. If nextFrame returns false, the animation will stop.
                         class FloatUpAnimation
                           def nextFrame(view)
                             new_eye = view.camera.eye
                             new_eye.z = new_eye.z + 1.0
                             view.camera.set(new_eye, view.camera.target, view.camera.up)
                             view.show_frame
                             return new_eye.z < 500.0
                           end
                         end

                         # This adds an item to the Camera menu to activate our custom animation.
                         UI.menu("Camera").add_item("Run Float Up Animation") {
                           Sketchup.active_model.active_view.animation = FloatUpAnimation.new
                         }


                    It makes a class named FloatUpAnimation, but no mention of Animation. A bit confusing.
                    Is it like the Observers?
                    Should it say class FloatUpAnimation < Animation


                    Hi,

                    Can someone post an example of using the "nextFrame(view)" definition for moving an entity object instead of a camara?


                    My objective is to create a game in SketchUp similar to the one I am making with ruby and gosu named "Resballiza" ... Here is a link for more info;

                    http://www.libgosu.org/cgi-bin/mwf/topic_show.pl?tid=815


                    So far I have studied JS Move Tool by Jan Sandstrom and changed the Keys for my game style but the "Typematic effects" bug in windows is giving me a hard time.
                    I have also tried to understand the scrip in the "Prince of IO" game but get lost with anything that has to do with Webdialog related scripts. Please any help in demonstrating a simple object animation that is as simple as the FloatUpAnimation scrip for the camera let me know.


                    Thanks
                    0
                    User avatar
                    renderiza 
                    Premium Member
                    Premium Member
                     

                    Re: New API doc - typos and questions

                    Postby TIG » Tue Sep 25, 2012 11:03 am

                    The menu item's code
                    Sketchup.active_model.active_view.animation = FloatUpAnimation.new
                    runs that class, making a new animation associated with the 'view', the class calls the lone special method nextFrame(view) - which affects the view's camera when it resets it with a new_eye position and uses show_frame to update the view...
                    The '.animation' is a method applied to a view, no a 'separate' class in it's own right...
                    Your own class that you pass to the view.animation can do various things inside the nextFrame(view) method - changing the camera's eye position is just one example...

                    It is an awkwardly set up method/class - but it will work as the example...
                    0
                    TIG
                    User avatar
                    TIG 
                    Global Moderator
                     

                    Re: New API doc - typos and questions

                    Postby renderiza » Tue Sep 25, 2012 9:22 pm

                    Hi,

                    Thanks TIG for explaining that


                    I found this topic and it solves animating an object like I wanted to but I can't make a file.rb for leading in the plugins menu. It shows me this error;


                    Load Errors
                    Undefined method ‘transform!’ for nil:NilClassError Loading File
                    jumper.rb
                    undefined method ‘transform!’ for nil: NilClass


                    If anyone nows how to solve this let me know

                    Thanks
                    0
                    User avatar
                    renderiza 
                    Premium Member
                    Premium Member
                     

                    Re: New API doc - typos and questions

                    Postby Dan Rathbun » Tue Sep 25, 2012 9:26 pm

                    Burkhard wrote:I could not find a send_action value for Display or toggle the Measurement Toolbar. Just VCB hide / unhide with Statusbar.

                    The VCB ("Measurements") toolbar is special. (It's really a ControlBar.) There are many native tools, and Ruby Tools that rely upon it. Therefore it cannot be hidden like other toolbars. (This is by design.)

                    However when you "toggle" it, instead of it being a hide/show toggle, it is actually a StatusBar dock/undock toggle.

                    Burkhard wrote:Is there an undocumented Value?

                    Yes the dock/undock toggle is Sketchup.send_action(24157), but on PC only.

                    When you undock it from the StatusBar, it will take on the user's undocked setting, which is either floating (the default,) or docked to one of the Toolbar Containers (top, left, right or bottom.)

                    Be aware that the location of the VCB is a user preference. I myself have it undocked from the StatusBar, and docked in the top toolbar container, 2nd row, 2nd position (following the Layer ControlBar.)
                    If your plugin was to call Sketchup.send_action(24157), the VCB would be moved back onto the StatusBar (where I hate it.) So you risk upsetting users if you move the VCB somewhere the user does not want it.

                    :idea:
                    0
                      I'm not here much anymore. But a PM will fire email notifications.
                      User avatar
                      Dan Rathbun 
                      PluginStore Author
                      PluginStore Author
                       

                      Re: New API doc - typos and questions

                      Postby Dan Rathbun » Tue Sep 25, 2012 9:34 pm

                      Renderiza wrote:If anyone nows how to solve this let me know

                      You really should have started a new topic for your issue. (This topic about errors in the online API Dictionary.)

                      You need to learn to read Exception messages. The full message will have a line number in your file where the error happen.
                      You are calling the instance method transform! upon an object that you think is a Sketchup::Group instance (guessing,) ... but something had gone wrong in a previous statement when you assigned the ref to the object identifier, and some other method returned nil (the singleton instance of the NilClass.)

                      It is standard in Ruby to first check for success, before continuing.

                      Code: Select all
                      obj = ents.add_edge( pt1, p2 )
                      if obj # evals true if not false or nil
                        obj.transform!(tr)
                      else
                        UI.messagebox("Error created the Edge object!")
                      end
                      0
                        I'm not here much anymore. But a PM will fire email notifications.
                        User avatar
                        Dan Rathbun 
                        PluginStore Author
                        PluginStore Author
                         

                        Re: New API doc - typos and questions

                        Postby Dan Rathbun » Tue Sep 25, 2012 9:43 pm

                        Dan Rathbun wrote:
                        Renderiza wrote:If anyone nows how to solve this let me know

                        You really should have started a new topic for your issue. (This topic about errors in the online API Dictionary.)

                        Don't worry about that now (this topic is so long and cluttered it does not matter much. And likely will be locked when the next version of the online API Dictionary is updated.)

                        Dan Rathbun wrote:You need to learn to read Exception messages. The full message will have a line number in your file where the error happen.

                        Move your file (and all your authored scripts,) into a "Renderiza" subdir of the Plugins dir.

                        When debugging.. start Sketchup, then open the Ruby Console.

                        Enter load("Renderiza/myfile.rb")

                        You'll see a more complete Exception message output to the console.
                        0
                          I'm not here much anymore. But a PM will fire email notifications.
                          User avatar
                          Dan Rathbun 
                          PluginStore Author
                          PluginStore Author
                           

                          Re: New API doc - typos and questions

                          Postby renderiza » Tue Sep 25, 2012 10:16 pm

                          Thanks Dan Rathbun for teaching me how to debug inside Ruby Console.
                          I forgor to post the topic link I was referring to…
                          viewtopic.php?f=180&t=25498

                          I still can’t find a way to load the jumper.rb and animate the object when active but I will sonn figure it out. And I promise that for next time I will make a new topic for my issues. :thumb:

                          Thanks
                          0
                          User avatar
                          renderiza 
                          Premium Member
                          Premium Member
                           

                          Re: New API doc - typos and questions

                          Postby wood_galaxy » Fri Nov 23, 2012 10:58 am

                          Hi !
                          I haven't seen if it had benn reported but :
                          In Attribute reporting Tutorial in the function :
                          Code: Select all
                          def clean_for_xml(value)
                              value = value.to_s
                              value = value.gsub(/\</,'<')
                              value = value.gsub(/\>/,'>')
                              value = value.gsub(/\"/,'"')
                              value = value.gsub(/\'/,''')
                              return value
                            end

                          The last gsub make that the rest of code is a comment...
                          0

                          wood_galaxy 
                           

                          Re: New API doc - typos and questions

                          Postby TIG » Fri Nov 23, 2012 11:10 am

                          @wood_galaxy

                          ???
                          .gsub(/\'/,''')
                          should be
                          .gsub(/\'/,"'")
                          to 'wrap' the lone ' properly...

                          I'm unclear what you put in and what you expect to come out here :?
                          The
                          value = value.gsub(/\</,'<')
                          could be made as
                          value.gsub!(/\</,'<')
                          changing 'value' rather than reassigning it to a modified version of itself.
                          You could also 'string' the gsub changes into one line...
                          return value.to_s.gsub(/\</,'<').gsub(/\>/,'>').gsub(/\"/,'"').gsub(/\'/,"'")
                          Although it's easier to read what you are doing your way.
                          It'd probably be slightly faster - but relatively unnoticeable if only a few values are processed...
                          Can you clarify?
                          0
                          TIG
                          User avatar
                          TIG 
                          Global Moderator
                           

                          Re: New API doc - typos and questions

                          Postby wood_galaxy » Fri Nov 23, 2012 11:32 am

                          I thought this topic was used to identify inconsistencies in the API doc.
                          I had just noticed that the code of the tutorial was a mistake.
                          I started in ruby but I think the line "value = value.gsub(/\'/,''')" contains an error.
                          Maybe I'm wrong and that it is normal that the two following functions can be found commented.
                          So TIG you say it should be .gsub(/\'/,"'"). That's what I wanted to know and get noticed.
                          Sorry for the inconvenience.
                          0

                          wood_galaxy 
                           

                          SketchUcation One-Liner Adverts

                          by Ad Machine » 5 minutes ago



                          Ad Machine 
                          Robot
                           

                          PreviousNext


                           

                          Return to Developers' Forum

                          Who is online

                          Users browsing this forum: No registered users and 4 guests

                          Visit our sponsors: