Formatting differences on C SDK docs

Questions
#1

I want to update my VS Code snippets to latest (178), but I found newly added C sdk methods has different writing style.

Not sure if this is intentional. Is it?

Generally, functions are documented like this: namespace::function()

Ex:

dmSSLSocket::new
dmThread::Join()   
dmBuffer::Copy

But latest functions are written without the namespace:

New() //dmSocket 
SetPosition() // dmGameObject
RegisterCallback() // dmExtension
1 Like
#2

It has a bit to do with the fact that I think our documentation looked very crowded on the documentation page, with a lot of redundant data.

Tbh, I don’t consider our documentation page a very robust “api” to parse info from. We might change how things are structured and/or look from one day to another.

Instead I suggest you use our generated documentation directly.
It is built with each release (dev, beta or stable).
We should add a link to it to our d.defold.com releases too (or do you see any problems with this @britzl?)

http://d.defold.com/archive/stable/af6a29c2a1e2545e2d033790089c606ac9f0bb7a/engine/share/ref-doc.zip

The archive contains .json, .sdoc and .script_api

E.g. doc/dmSocket.json

{
  "info": {
    "group": "DEFOLD SDK", 
    "description": "Socket functions.", 
    "namespace": "dmSocket", 
    "brief": "SDK Socket API documentation", 
    "file": "dmsdk/dlib/socket.h", 
    "path": "engine/dlib/src/dmsdk/dlib/socket.h", 
    "name": "Socket"
  }, 
  "elements": [
    {
      "replaces": "", 
      "description": "Socket default timeout value", 
      "parameters": [], 
      "returnvalues": [], 
      "notes": [], 
      "brief": "Socket default timeout value", 
      "examples": "", 
      "members": [], 
      "error": "", 
      "tparams": [], 
      "type": "VARIABLE", 
      "name": "SOCKET_TIMEOUT"
    }, 
    {
      "replaces": "", 
      "description": "Socket type definition", 
      "parameters": [], 
      "returnvalues": [], 
      "notes": [], 
      "brief": "Socket type definition", 
      "examples": "", 
      "members": [], 
      "error": "", 
      "tparams": [], 
      "type": "TYPEDEF", 
      "name": "Socket"
    }, 
... loong file ...
1 Like
#3

Also note that we have the info.json which you can parse for the latest stable sha1:

http://d.defold.com/stable/info.json

This way you could potentially make the plugin autocheck version and download new info. :slight_smile:

#4

I’m already doing this by downloading the latest version and parsing the json files by using simple python script: https://github.com/selimanac/defold-vsc-snippets/blob/master/src/defold_json_convert.py

1 Like
#5

It would be nice to have auto check feature available on vscode plugin but I hate JS… So I prefer to manually update once a while. Yes I’m lazy, I know :slight_smile:

#6

So in my case, it is better to use namespaces when writing code. Auto complete works better when you type the namespace. Parsing and formatting different types is a bit of a problem. I’m going to left it as it is for now.
Thank you.

1 Like
#7

No problem! And quite annoying that we don’t list it there!

PR: https://github.com/defold/defold/pull/5461

2 Likes