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

VirtualVirgin

I am wondering what happened with the .md files here.
https://github.com/christophhart/hise_documentation/tree/master/scripting/scripting-api
I am supposing that an automated process to generate the files is leaving most of them blank?

d.healey

@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.

Christoph Hart

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

VirtualVirgin

@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)

VirtualVirgin

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

Unlocker.txt

d.healey

@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

VirtualVirgin

@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?

d.healey

@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.

VirtualVirgin

@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.

d.healey

@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.

Christoph Hart

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.

VirtualVirgin

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

Aw poor @VirtualVirgin that was half an hour that you'll never get back

"Aw poor @VirtualVirgin that was half an hour that you'll never get back"

No worries! Was learning how to generate markdown files from text.
I made text files of all of the classes in the API, then ran a python script to transform it to markdown. Just a learning experience. I then went on the generate JSON for the API with the following schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Scripting API Method",
  "type": "object",
  "properties": {
    "class": {
      "type": "string",
      "description": "The class this method belongs to."
    },
    "method": {
      "type": "string",
      "description": "The method name."
    },
    "description": {
      "type": "string",
      "description": "A description of what the method does."
    },
    "syntax": {
      "type": "string",
      "description": "The usage syntax string for the method."
    },
    "parameters": {
      "type": "array",
      "description": "List of method parameters.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The parameter name."
          },
          "type": {
            "type": "string",
            "description": "The parameter type."
          },
          "optional": {
            "type": "boolean",
            "description": "Whether the parameter is optional."
          },
          "description": {
            "type": "string",
            "description": "A description of the parameter."
          }
        },
        "required": ["name", "type", "optional", "description"],
        "additionalProperties": false
      }
    },
    "returns": {
      "type": "string",
      "description": "The return type of the method."
    },
    "examples": {
      "type": "array",
      "description": "Code examples demonstrating usage.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "class",
    "method",
    "description",
    "syntax",
    "parameters",
    "returns"
  ],
  "additionalProperties": false
}

Which makes this for example:

[
  {
    "class": "Array",
    "method": "clear",
    "description": "Clears the array.",
    "syntax": "Array.clear()",
    "parameters": [],
    "returns": "",
    "examples": [
      "const var arr = []; // Declare an array\n\n// preallocate 10 elements, do this if you\n// know how many elements you are about to insert\narr.reserve(10); \n\nfor(i = 0; i < 10; i++)\n{\n\t// Add an element to the end of the array\n\tarr.push(Math.randInt(0, 1000));\n}\n\nConsole.print(trace(arr)); // [ 523, 5, 76, 345, 765, 45, 977, 223, 44, 54]\n\narr.clear();\n\nConsole.print(trace(arr)); // []"
    ]
  },
  {
    "class": "Array",
    "method": "clone",
    "description": "Creates a deep copy of the array.",
    "syntax": "Array.clone()",
    "parameters": [],
    "returns": "A deep copy of the array.",
    "examples": [
      "const arr1 = [0, 1];\n\nvar arr2 = arr1;\n\n// Changing any element in arr2 will also change it in arr1\narr2[0] = 22;\nConsole.print(trace(arr1)); // [22, 1]\n\n// Reset the element 0 back to 0\narr1[0] = 0;\n\n// Cloning the array creates a new dataset in memory, separate from the original array\narr2 = arr1.clone();\nConsole.print(trace(arr1));\narr2[0] = 22;\nConsole.print(trace(arr2));"
    ]
  },

I'm sure this is all elementary for you and David, but I'm just learning how to do some these data formats and transformations with parsers etc.