Opinion: For AHKv2, We should move away from writing Examples into inline comment docs, adopt if __main__
Posted: 13 Feb 2024, 02:40
This is addressed towards authors in the community of Class Libs. I believe we should adopt the python-esk clean data standard.
The below example and titles' thesis would not only clean up organization and standardized, it would heavily encourage an abstracted focused formatting.
As in python, a script should be able to run on its own without the required parent script.
Ill use a positive example, then an example of my scripts docs which I try to standardize, but most lib writters I see/fork don't standardize even for Javadoc/js format.
Positive example
Negative example, and how many classes are written now. Using an old script of my own, not picking on anyone.
The below example and titles' thesis would not only clean up organization and standardized, it would heavily encourage an abstracted focused formatting.
As in python, a script should be able to run on its own without the required parent script.
Ill use a positive example, then an example of my scripts docs which I try to standardize, but most lib writters I see/fork don't standardize even for Javadoc/js format.
Positive example
Code: Select all
if A_LineFile = A_ScriptFullPath
pantryExample()
pantryExample()
{
; Example usage:
PantryAPI.PantryID := "YOUR_PANTRY_ID" ; Set your Pantry ID
PantryAPI.BasketName := "YOUR_BASKET_NAME" ; Set your Basket Name
; https://getpantry.cloud/#
MsgBox PantryAPI.NewBasket()
; continues.....
}
class PantryAPI {
static PantryID := "" ; Your Pantry ID here
static BasketName := "" ; Your Basket Name here
; Method to update the contents of a basket
static UpdateBasket(newData) {
; continues....
Code: Select all
#Include _Jsons.ahk
/*
@source https://github.com/samfisherirl/Github.ahk-API-for-AHKv2
@method Github.latest(Username,Repository_Name)
return {
downloadURLs: [
"http://github.com/release.zip",
"http://github.com/release.rar"
],
version: "",
change_notes: "",
date: "",
}
@method Github.historicReleases(Username,Repository_Name)
array of objects => [{
downloadURL: "",
version: "",
change_notes: "",
date: ""
}]
@func this.Download(url,path)
improves on download():
- if user provides wrong extension, function will apply proper extension
- allows user to provide directory
example: Providing A_ScriptDir to Download will throw error
Providing A_ScriptDir to Github.Download() will supply Download() with release name
*/
class Github
{
static source_zip := ""
static url := false
static usernamePlusRepo := false