HISE Logo Forum
    • Categories
    • Register
    • Login

    Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?

    Scheduled Pinned Locked Moved Documentation
    11 Posts 3 Posters 89 Views
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • d.healeyD
      d.healey @VirtualVirgin
      last edited by

      @VirtualVirgin A lot of the scripting documentation is generated automatically from the comments within the source code. I believe those placeholder, if populated, will override the auto generated docs.

      Libre Wave - Freedom respecting instruments and effects
      My Patreon - HISE tutorials
      YouTube Channel - Public HISE tutorials

      Christoph HartC 1 Reply Last reply Reply Quote 0
      • Christoph HartC
        Christoph Hart @d.healey
        last edited by

        They are autogenerated and empty so that you can edit them and fill the gaps :)

        VirtualVirginV 1 Reply Last reply Reply Quote 0
        • VirtualVirginV
          VirtualVirgin @Christoph Hart
          last edited by

          @Christoph-Hart I put the Scripting API into markdown files with on file per class. Would that be useful for the Git Docs? Here is an example:

          Unlocker

          The LicenseUnlocker will aid you in managing HISEs keyfile and unlocking system.You can create an Unlocker object with Engine.createLicenseUnlocker() .

          const var Unlocker = Engine.createLicenseUnlocker();
          

          Class methods

          canExpire

          Checks if the unlocker's license system has an expiration date.

          Unlocker.canExpire()
          

          checkExpirationData

          If the unlocker has an expiration date, it will check it against the RSA encoded time string from the server.

          Unlocker.checkExpirationData( String encodedTimeString)
          

          checkMuseHub

          If you use the MuseHub SDK this will try to activate the plugin using their SDK.

          Unlocker.checkMuseHub(var resultCallback)
          

          contains

          Checks if the string contains the given substring.

          Unlocker.contains(String otherString)
          

          getLicenseKeyFile

          Returns the license key file as File object.

          Unlocker.getLicenseKeyFile()
          

          getRegisteredMachineId

          Returns the machine ID that is encoded into the license file. This does not look in the encrypted blob, but just parses the header string.

          Unlocker.getRegisteredMachineId()
          

          getUserEmail

          Returns the user email that was used for the registration.

          Unlocker.getUserEmail()
          

          isUnlocked

          Checks if the registration went OK.

          Unlocker.isUnlocked()
          

          isValidKeyFile

          Checks if the possibleKeyData might contain a key file.

          Unlocker.isValidKeyFile(var possibleKeyData)
          

          keyFileExists

          Checks whether the key file exists.

          Unlocker.keyFileExists()
          

          loadKeyFile

          This checks if there is a key file and applies it.

          Unlocker.loadKeyFile()
          

          setProductCheckFunction

          Sets a function that performs a product name check and expects to return true or false for a match.

          Unlocker.setProductCheckFunction(var f)
          

          writeKeyFile

          Writes the key data to the location.

          Unlocker.writeKeyFile( String keyData)
          

          You can listen to my orchestral mockups here:
          https://www.virtualvirgin.net/

          d.healeyD 1 Reply Last reply Reply Quote 0
          • VirtualVirginV
            VirtualVirgin
            last edited by

            Ok, the uploads doesn't like .md format so I just put it in a text file:

            Unlocker.txt

            You can listen to my orchestral mockups here:
            https://www.virtualvirgin.net/

            1 Reply Last reply Reply Quote 0
            • d.healeyD
              d.healey @VirtualVirgin
              last edited by

              @VirtualVirgin said in Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?:

              I put the Scripting API into markdown files with on file per class. Would that be useful for the Git Docs? Here is an example:

              Isn't that the same as the autogenerated docs? https://docs.hise.audio/scripting/scripting-api/unlocker/index.html

              Libre Wave - Freedom respecting instruments and effects
              My Patreon - HISE tutorials
              YouTube Channel - Public HISE tutorials

              VirtualVirginV 1 Reply Last reply Reply Quote 0
              • VirtualVirginV
                VirtualVirgin @d.healey
                last edited by

                @d-healey I hope so! That is what I made them from. I just wanted to be able to use the Scripting API in markdown format, but your response makes me think that I am lacking context or missing something obvious?

                You can listen to my orchestral mockups here:
                https://www.virtualvirgin.net/

                d.healeyD 1 Reply Last reply Reply Quote 0
                • d.healeyD
                  d.healey @VirtualVirgin
                  last edited by

                  @VirtualVirgin said in Looking into the hise_documentation on GitHub- any reason why a majority of the markdown files are empty for the Scripting API?:

                  I am lacking context or missing something obvious?

                  Or I am :) I'm not sure what your goal is.

                  Libre Wave - Freedom respecting instruments and effects
                  My Patreon - HISE tutorials
                  YouTube Channel - Public HISE tutorials

                  VirtualVirginV 1 Reply Last reply Reply Quote 0
                  • VirtualVirginV
                    VirtualVirgin @d.healey
                    last edited by

                    @d-healey Just that if the markdown files for the Documentation on GitHub has mostly blank files, maybe these are useful? Or maybe I am not understanding the purpose of the markdown files on the GitHub site.

                    You can listen to my orchestral mockups here:
                    https://www.virtualvirgin.net/

                    d.healeyD 1 Reply Last reply Reply Quote 0
                    • d.healeyD
                      d.healey @VirtualVirgin
                      last edited by

                      @VirtualVirgin The documentation on the docs website is autogenerated from the comments in the HISE source code. If you want to change that auto-generated documentation to say something else then you can add your changes to the markdown files.

                      There is no advantage to putting the autogenerated content we already have into the markdown file, because then if something changes in the source code the documentation won't automatically follow it.

                      Libre Wave - Freedom respecting instruments and effects
                      My Patreon - HISE tutorials
                      YouTube Channel - Public HISE tutorials

                      Christoph HartC 1 Reply Last reply Reply Quote 0
                      • Christoph HartC
                        Christoph Hart @d.healey
                        last edited by

                        Aw poor @VirtualVirgin that was half an hour that you'll never get back, sorry for being not clear enough.

                        So basically what happens is that I'm taking the markdown files from GitHub to build the HISE docs website. The documentation generator takes some autogenerated code and merges it with the additional text from GitHub - this way it stays always up to date and the formatting is consistent.

                        Now the problem was at some point (and we discussed this at some HISE meetup) that the user engagement with the task of contributing to the HISE documentation is mostly hindered by the complicated system that people have to follow in order to write the docs so we came up with the solution that the HISE documentation generator just creates these empty markdown files for all undocumented API methods that have the proper file name / folder scheme so that they will show up later in the docs. From there, people can just edit the empty files to add more context, code examples or more thorough explanations than the one liner API help that is being extracted from the HISE source code.

                        So what looks like a bug to you - empty text files - is actually a feature that is supposed to lower the barrier for user contributions.

                        1 Reply Last reply Reply Quote 0
                        • First post
                          Last post

                        37

                        Online

                        2.0k

                        Users

                        12.6k

                        Topics

                        109.6k

                        Posts