@hgy29 thanks. Even though it could be improved, the current JSON output is usable. All it really needs is to include the return values and it's good to go.
The following pages currently have bad formatting in either their parameter or result sections: TexturePack.new Matrix:perspectiveProjection Application:getDeviceHeight TextureRegion.new Bitmap:setTexture Bitmap:setTextureRegion Pixel.new Pixel.setColor Vogon.new Vogon:writePoetry Vogon:recitePoetry Thread.new Thread:setFunction Thread:execute Thread:resume Thread.yield Thread:status Thread:getNumLogicalCores Thread.sendData Thread:fetchData Thread:getResults Noise:noise Noise:noise2D Noise:noise3D Noise:setColorLookup Noise:getTexture Noise:getTileTexture Noise:gradientPerturb2D Noise:gradientPerturb3D Noise:gradientPerturbFractal2D Noise:gradientPerturbFractal3D Noise:simplex4D Noise:whiteNoise3DInt Noise:whiteNoise4DInt
Some method pages also have multiple parameter sections because those method can be overloaded. There are also several different ways people have decided to express overloading.
Bad formatting, multiple sections, and inconsistent syntax all cause the API reference script that @hgy29 made output broken data.
As such, it is pretty nigh impossible for anyone to programmatically do anything of any worth with the output data.
For bad formatting there is really no solution other than change the system used for editing the documentation so that all edits can be validated before they are committed to the database.
Documenting overloaded methods could be done by having multiple documents, one for each overload. In theory it would be good to have those method urls include the parameters as to not confuse the reader. Ideally I'd prefer all API method urls to contain the parameters as well.
I'll commit to fixing the following wiki pages... TexturePack.new Matrix:perspectiveProjection Application:getDeviceHeight TextureRegion.new Bitmap:setTexture Bitmap:setTextureRegion Pixel.new Pixel.setColor
Oh, does anyone else have any ideas on how to improve the wiki?
To make a new page, you just need to put a link to it somewhere. For a method, add the link to the corresponding page. Once the link is added, you'll be able to click on it to create the page.
About making one overload per page, it can be problematic, since the page name is expected to be the name of the function. I think it would be better to have multiple forms of the same function on the same page (my tool doesn't handle it now, but I will modify it to accept such scenario).
Currently the script returns a "function" object containing the args, returns, and description. Would the script instead have an array of those instead, and move "description" out of there?
The args from the main object would be pretty much redundant in that case also.
So the output for Bitmap.new might look a bit like..
{"Bitmap": {"name": "Bitmap.new",
"functions": [{"args": [{"name": "texture",
"type": "Texture",
"description": "A Texture object.<br/>"}],
"returns": [],
},
{"args": [{"name": "textureBase",
"type": "TextureBase",
"description": "A TextureBase object.<br/>"}],
"returns": [],
},
]"description": "Creates a new [[Special:MyLanguage/Bitmap|Bitmap]] object.<source lang=\"lua\">Bitmap.new(texture)</source>""short_description": "creates a new Bitmap object"}},
Oh, and would it be possible for the "arg" objects to have an "optional" boolean? It's not required but would be kind of nice
The following pages currently have bad formatting in either their parameter or result sections: ... Noise:noise Noise:noise2D Noise:noise3D Noise:setColorLookup Noise:getTexture Noise:getTileTexture Noise:gradientPerturb2D Noise:gradientPerturb3D Noise:gradientPerturbFractal2D Noise:gradientPerturbFractal3D Noise:simplex4D Noise:whiteNoise3DInt Noise:whiteNoise4DInt
number = Noise:noise returns: noise value args: x, y, z (all optional) description: generates a noise value based on 3 values (optional args are 0 by default)
Noise:noise2D returns: noise value description: generates a noise value based on 2 values args: x, y
Noise:noise3D returns: noise value description: generates a noise value based on 3 values args: x, y, z
Noise:setColorLookup returns: - description: sets a height color map table to generate a texture args: table
Noise:getTexture returns: texture description: generate a texture args: -
Noise:getTileTexture returns: texture description: generate a repeatable texture args: -
Noise:simplex4D returns: get 4D simplex noise description: generates a noise value based on 4 values args: x, y, z, w
Noise:whiteNoise3DInt returns: get 3D white noise (args must be 3 ints) description: generates a white noise value based on 3 values args: x, y, z
Noise:whiteNoise4DInt returns: get 4D white noise (args must be 4 ints) description: generates a white noise value based on 4 values args: x, y, z, w
Idk for these ones, sorry
Noise:gradientPerturb2D returns: number, number description: args: -
Noise:gradientPerturb3D returns: number, number, number description: args: -
Noise:gradientPerturbFractal2D returns: number, number description: args: -
Noise:gradientPerturbFractal3D returns: number, number, number description: args: -
Would it be possible for the new Java script to also export the other stuff like examples and fields such as "inherits from", "platforms", etc?
I think that over the remainder of my school break I'd like to attempt to create my own Gideros API editor. I've created a MySQL database, and SQL script to create all of the tables, and am now beginning to use the output from your previous script to generate SQL queries to populate the database.
@antix, yes it should be doable, I'll have a look at it. Meanwhile I improved my script already, it now handles multiple functions per page (in case they have several forms), better overall parsing, reports optional args and also reports some errors. https://wiki.gideros.rocks/gidapiref.json
Coder, video game industry veteran (since the '80s, ❤'s assembler), arrested - never convicted hacker (in the '90s), dad of five, he/him (if that even matters!). https://deluxepixel.com
I added 'Since', 'Platforms' and 'Inherits' to my doc scraper. About translation, I don't think I can remove them automatically, so I'd say let's not bother anymore with them and write doc without special tags for translation from now on.
I'm beginning to test what I have and even though it's pretty rough, I'd like to publish it as a VSCode extension soon.
Whilst creating documents I notice that giderosmobile.com does not support HTTPS and can not be added as a hyperlink in the documentation. Might the website be made HTTPS friendly with any relative ease?
Given the state of the gideros website maybe it's better that no linking is possible
I'm making some small amount of progress with my Gideros Visual Studio integration and have discovered a few annoying things regarding the wiki...
1. Some function parameters have spaces in them. This is very bad, please don't do this anymore I've fixed all of those.
2. Some parameters are Lua reserved words. This is also very bad, please don't do that anymore either Also fixed all of those.
3. Functions in the main API pages are not in any order so it's really hard to find anything quickly. If you are adding more functions, please insert them at the correct position (in A to Z order), please don't just mash them on at the end of the list thanks
4. Some functions have extraneous parameters which are not actually parameters, but instead they are descriptions of how a particular parameter should be structured. This is so bad, please don't do that anymore. If any structure that is passed as a parameter needs explaining.. please explain it in the example code. see "Noise:setColorLookup" which I've cleaned up
In general I'm finding the wiki tedious with it's poor navigation and especially it's total lack of any barrier to making bad edits to anything. @MoKaLux you're a true hero. I don't know how you can use that thing and not feel suicidal
3. Functions in the main API pages are not in any order so it's really hard to find anything quickly. If you are adding more functions, please insert them at the correct position (in A to Z order), please don't just mash them on at the end of the list thanks
When you look closely you will find that they are indeed ordered: - first we list the class with a dot (I don't know what they are called) in alphabetical order - then we list the functions with columns (:) in alphabetical order
In general I'm finding the wiki tedious with it's poor navigation and especially it's total lack of any barrier to making bad edits to anything. @MoKaLux you're a true hero. I don't know how you can use that thing and not feel suicidal
In fact I like gideros wiki navigation is easy. Bad edits are there to be fixed There are still a lot of things missing from the wiki (new plugins not added, remove all translation tags stuff, adding more examples, fixing typos, ...). I like doing it because that's how I learnt gideros. I will hopefully follow your recommendations for the wiki. Thank you antix for your work on VS code .
@hgy29 I've only noticed that every nameSpace reports "Missing summary description" in the errors array in "https://wiki.gideros.rocks/gidapiref.json", however the nameSpaces actually contain descriptions on the wiki. Maybe the script isn't getting the correct variable there?
Also of interest is that zlib (at least) is exported with empty function arrays for each of its methods.
Comments
Except that some things are missing args, like Bitmap.new(texture)..
The following pages currently have bad formatting in either their parameter or result sections:
TexturePack.new
Matrix:perspectiveProjection
Application:getDeviceHeight
TextureRegion.new
Bitmap:setTexture
Bitmap:setTextureRegion
Pixel.new
Pixel.setColor
Vogon.new
Vogon:writePoetry
Vogon:recitePoetry
Thread.new
Thread:setFunction
Thread:execute
Thread:resume
Thread.yield
Thread:status
Thread:getNumLogicalCores
Thread.sendData
Thread:fetchData
Thread:getResults
Noise:noise
Noise:noise2D
Noise:noise3D
Noise:setColorLookup
Noise:getTexture
Noise:getTileTexture
Noise:gradientPerturb2D
Noise:gradientPerturb3D
Noise:gradientPerturbFractal2D
Noise:gradientPerturbFractal3D
Noise:simplex4D
Noise:whiteNoise3DInt
Noise:whiteNoise4DInt
Some method pages also have multiple parameter sections because those method can be overloaded. There are also several different ways people have decided to express overloading.
Bad formatting, multiple sections, and inconsistent syntax all cause the API reference script that @hgy29 made output broken data.
As such, it is pretty nigh impossible for anyone to programmatically do anything of any worth with the output data.
For bad formatting there is really no solution other than change the system used for editing the documentation so that all edits can be validated before they are committed to the database.
Documenting overloaded methods could be done by having multiple documents, one for each overload. In theory it would be good to have those method urls include the parameters as to not confuse the reader. Ideally I'd prefer all API method urls to contain the parameters as well.
I'll commit to fixing the following wiki pages...
TexturePack.new
Matrix:perspectiveProjection
Application:getDeviceHeight
TextureRegion.new
Bitmap:setTexture
Bitmap:setTextureRegion
Pixel.new
Pixel.setColor
Oh, does anyone else have any ideas on how to improve the wiki?
Likes: antix
I suppose I need a new page for each overload.
About making one overload per page, it can be problematic, since the page name is expected to be the name of the function. I think it would be better to have multiple forms of the same function on the same page (my tool doesn't handle it now, but I will modify it to accept such scenario).
Likes: antix
Okay if you look at https://wiki.gideros.rocks/index.php/Special:MyLanguage/Pixel.new then that's an example of a page that has multiple description, and parameter sections. That would be a good test one to get your script working.
Currently the script returns a "function" object containing the args, returns, and description. Would the script instead have an array of those instead, and move "description" out of there?
The args from the main object would be pretty much redundant in that case also.
So the output for Bitmap.new might look a bit like..
[[Special:MyLanguage/Bitmap|Bitmap]]
That should be the norm:
[[Bitmap]]
Likes: keszegh, MoKaLux, antix
returns: noise value
args: x, y, z (all optional)
description: generates a noise value based on 3 values (optional args are 0 by default)
Noise:noise2D
returns: noise value
description: generates a noise value based on 2 values
args: x, y
Noise:noise3D
returns: noise value
description: generates a noise value based on 3 values
args: x, y, z
Noise:setColorLookup
returns: -
description: sets a height color map table to generate a texture
args: table
Noise:getTexture
returns: texture
description: generate a texture
args: -
Noise:getTileTexture
returns: texture
description: generate a repeatable texture
args: -
Noise:simplex4D
returns: get 4D simplex noise
description: generates a noise value based on 4 values
args: x, y, z, w
Noise:whiteNoise3DInt
returns: get 3D white noise (args must be 3 ints)
description: generates a white noise value based on 3 values
args: x, y, z
Noise:whiteNoise4DInt
returns: get 4D white noise (args must be 4 ints)
description: generates a white noise value based on 4 values
args: x, y, z, w
Idk for these ones, sorry
Noise:gradientPerturb2D
returns: number, number
description:
args: -
Noise:gradientPerturb3D
returns: number, number, number
description:
args: -
Noise:gradientPerturbFractal2D
returns: number, number
description:
args: -
Noise:gradientPerturbFractal3D
returns: number, number, number
description:
args: -
Likes: MoKaLux, antix
Likes: antix
I've also discovered a heap of methods (particularly in the b2 nameSpace) with no descriptions.
Would it be possible for the new Java script to also export the other stuff like examples and fields such as "inherits from", "platforms", etc?
I think that over the remainder of my school break I'd like to attempt to create my own Gideros API editor. I've created a MySQL database, and SQL script to create all of the tables, and am now beginning to use the output from your previous script to generate SQL queries to populate the database.
Meanwhile I improved my script already, it now handles multiple functions per page (in case they have several forms), better overall parsing, reports optional args and also reports some errors.
https://wiki.gideros.rocks/gidapiref.json
Likes: antix
Likes: MoKaLux
https://deluxepixel.com
About translation, I don't think I can remove them automatically, so I'd say let's not bother anymore with them and write doc without special tags for translation from now on.
Likes: SinisterSoft, MoKaLux, antix
Whilst creating documents I notice that giderosmobile.com does not support HTTPS and can not be added as a hyperlink in the documentation. Might the website be made HTTPS friendly with any relative ease?
Given the state of the gideros website maybe it's better that no linking is possible
Likes: keszegh
1. Some function parameters have spaces in them. This is very bad, please don't do this anymore I've fixed all of those.
2. Some parameters are Lua reserved words. This is also very bad, please don't do that anymore either Also fixed all of those.
3. Functions in the main API pages are not in any order so it's really hard to find anything quickly. If you are adding more functions, please insert them at the correct position (in A to Z order), please don't just mash them on at the end of the list thanks
4. Some functions have extraneous parameters which are not actually parameters, but instead they are descriptions of how a particular parameter should be structured. This is so bad, please don't do that anymore. If any structure that is passed as a parameter needs explaining.. please explain it in the example code. see "Noise:setColorLookup" which I've cleaned up
In general I'm finding the wiki tedious with it's poor navigation and especially it's total lack of any barrier to making bad edits to anything. @MoKaLux you're a true hero. I don't know how you can use that thing and not feel suicidal
Likes: keszegh
- first we list the class with a dot (I don't know what they are called) in alphabetical order
- then we list the functions with columns (:) in alphabetical order In fact I like gideros wiki navigation is easy.
Bad edits are there to be fixedThere are still a lot of things missing from the wiki (new plugins not added, remove all translation tags stuff, adding more examples, fixing typos, ...). I like doing it because that's how I learnt gideros.
I will hopefully follow your recommendations for the wiki.
Thank you antix for your work on VS code .
Likes: antix
All bad parameters have been fixed
Can't agree on the wiki being good though mate
Likes: MoKaLux
I've already fixed the offending wiki entries.
Likes: MoKaLux
Also of interest is that zlib (at least) is exported with empty function arrays for each of its methods.
Likes: antix
I notice on the wiki that every function name in the Application namespace are not lowercase, as they should be.