Better documentation

[erfanio]

Hi, I've noticed this project lacks good documentation on using it (installation is covered very well!). Especially there are a full gotchas that would be great to be documented.

• How the event handling work (ConnectXEvent, DisconnectXEvent, XEvent, XEventDefault)
• Since we can't override functions, the syntax for that (e.g. ConnectPaint, DisconnectPaint, Paint)
• Where the constants/types are (e.g. core.Qt__Key_Escape or gui.QKeyEvent)
• What happened to overloaded functions (1, 2, 3, 4, ... were added)

There is one more but it's not as easy to solve. Right now the only way to find the signature of the function passed to ConnectXEvent is to look at the generated go bindings (or look at the error when the signeture is wrong)

[rashwell]

I do like the bullets you point out here as each in its own way contributed to the steepness of the learning curve for me. First we could just start contributing too sections for each of the tough point, in the wiki for this project we could maybe just do some pull requests on this and see how concise we can get a page for each bullet. However in the end the source of the bindings will probably always need to be turned too at some point.

The major bullet I would add is one surrounding the even deeper stuff like creating structures with signals and slots etc, which then auto generates for your own structures all of the Connect, Disconnect, methods etc. I think I have a handle on the slot / signal creation, just struggling with the right way to emit signals. If I get it worked out I'll have a decent minor concise example that covers a lot of your bullets and more for people that like to learn by code examining as well

[rashwell]

@erfanio also I don't know if it will help but for your third bullet about the constants. Sometimes when I have to deal with windows environment, the intellisense for vscode is a little slow and hard to deal with mostly because gocode doesn't like 32bit / 64bit Qt stuff, etc.

I don't use ctags but there is gotags

What I do when I need to code for a long while in windows were the intellisense doesn't just do it well, in my notes files I usually keep a "constants" file around that I build with this little go app snippet (below). There are other modules in the qt binds, I only do this for the gui, widgets, core ones, but you could easily add the others. The code is below but it produces output across all three modules, that I pipe to a file that looks like this:

Type: core.QAbstractAnimation__DeletionPolicy
    core.QAbstractAnimation__KeepWhenStopped
    core.QAbstractAnimation__DeleteWhenStopped
Type: core.QAbstractAnimation__Direction
    core.QAbstractAnimation__Forward
    core.QAbstractAnimation__Backward

.... Cut for Length ....

Type: widget.QWizard__WizardPixmap
    widget.QWizard__WatermarkPixmap
    widget.QWizard__LogoPixmap
    widget.QWizard__BannerPixmap
    widget.QWizard__BackgroundPixmap
    widget.QWizard__NPixmaps
Type: widget.QWizard__WizardStyle
    widget.QWizard__ClassicStyle
    widget.QWizard__ModernStyle
    widget.QWizard__MacStyle
    widget.QWizard__AeroStyle
    widget.QWizard__NStyles

And this is the go program I use to produce it:

package main

import (
    "bufio"
    "fmt"
    "log"
    "os"
    "regexp"
    "sort"
)

// ModuleType for each module name and path
type ModuleType struct {
    name     string
    filepath string
}

func main() {

    gopath := os.Getenv("GOPATH")
    modules := []ModuleType{
        {name: "core", filepath: gopath + "/src/github.com/therecipe/qt/core/core.go"},
        {name: "widget", filepath: gopath + "/src/github.com/therecipe/qt/widgets/widgets.go"},
        {name: "gui", filepath: gopath + "/src/github.com/therecipe/qt/gui/gui.go"},
    }

    var constants map[string][]string
    constants = make(map[string][]string)

    for i := 0; i < len(modules); i++ {
        module := modules[i].name
        modpath := modules[i].filepath
        file, err := os.Open(modpath)
        if err != nil {
            log.Fatal(err)
        }
        defer file.Close()

        re := regexp.MustCompile("\\s*(Q[^ ]*)\\s*(Q[^ ]*) =.*")
        scanner := bufio.NewScanner(file)
        for scanner.Scan() {
            line := scanner.Text()
            constant := re.FindStringSubmatch(line)
            if constant != nil {
                _, present := constants[module+"."+constant[2]]
                if !present {
                    var o []string
                    o = make([]string, 0)
                    constants[module+"."+constant[2]] = o
                    constants[module+"."+constant[2]] = append(constants[module+"."+constant[2]], module+"."+constant[1])
                } else {
                    constants[module+"."+constant[2]] = append(constants[module+"."+constant[2]], module+"."+constant[1])
                }
            }
        }
        if err := scanner.Err(); err != nil {
            log.Fatal(err)
        }
    }
    var keys []string
    for k := range constants {
        keys = append(keys, k)
    }
    sort.Strings(keys)

    for _, k := range keys {
        fmt.Printf("Type: %s\n", k)
        for _, c := range constants[k] {
            fmt.Printf("\t%s\n", c)
        }
    }
}

[erfanio]

@rashwell Since all the constants/function/events/etc. have the same name (mostly) as the C++ counterpart, what I've been doing is grep -i someConstant in the source code file.

Also to your point about contributing to the wiki, I really feel like a proper documentation is needed, it's not something anyone but @therecipe can make since he's the only that that knows this project really well. I created this issue for reference if a documentation is under way or for future noobies (like me) who are searching the issues for figure out their problem

[r3k2]

+1 we need more side by side examples with C++ I think we lack lot of QT+go sockets like in the C++ QT apps lot of people use the build in QT but sometimes those are limited and use C++ sockets some similar options will be nice, example1 use QT+GO to call nmap, example2 use QT+GO sockets to make a nmap alike scanner.. etc.

[RadhiFadlillah]

Hey @bclermont, are there any info from @therecipe about this ? If not, I would like to take this issue.

Right now I've already created a doc generator which parses Go tags from source code, scrapes official Qt documentation, then combine them into one JSON file per Qt class. So I just need to create a simple Github pages to display those JSON files.

[jeanlucmongrain]

@RadhiFadlillah that sound like a good idea

@therecipe what you think?

[justinclift]

@RadhiFadlillah Good thinking. With the JSON output, what's that intended to be read by?

Asking because for docs I was thinking HTML output would be human readable... so it sounds like this is meant for feeding into some other kind of viewer? :smile:

[RadhiFadlillah]

@justinclift @bclermont @therecipe

I've finished making simple Github pages for displaying the JSON output from my doc generator. You can check it here.

Do note there are still many issues in the documentation. For starter, the search bar still not work, and there are some class or method that still don't have any description.

[justinclift]

@RadhiFadlillah That looks really really well done. Seems pretty excellent to me. :smile:

Hopefully @therecipe starts paying attention to this repo again soon, hopefully to share admin perms or something so things like your generated docs can be added without huge delays. 😀

[renannprado]

Nice work @RadhiFadlillah!

[therecipe]

@RadhiFadlillah That's fucking awesome, I really love it :) I like that it has the same clean/minimal look and feel as the official docs and also that you used raw HTML/JS/CSS instead of some framework. I made you a collaborator, so feel free to proceede as you wish. Thank you very much for you work :) (Also, is it possible to get the descriptions into the source as well? for godoc?)

I myself will try to be more active again over the following weeks, and aim to work at least part-time on this project starting from June/July. Then I will also start to look into the missing features, until then however I will just focus on bugfixes, a general cleanup and the wiki.

[r3k2]

are this documentation going to be put on the main site? @therecipe yeah man.. and give access to other people so the project continues :) nice work @RadhiFadlillah

[justinclift]

I made you a collaborator, so feel free to proceede as you wish.

@therecipe As a general thought :smile:, since https://github.com/therecipe only has the one repo (this one), maybe convert it from a user into an organisation? (pretty sure there's a button in the settings page somewhere)

That'd let you create user groups and assign roles/access/permissions to people. More powerful and fine grained than adding people as collaborators. Could be useful. :smile:

[RadhiFadlillah]

@therecipe thanks for making me collaborator.

Also, is it possible to get the descriptions into the source as well? for godoc?

Yep, it should be easy enough to do. However, I still have a job for the next few days, so I can only start working on it maybe around the end of January.

I agree with @justinclift, you should convert this repo into organization. However, before that, I suggest you to finally pick the name for this binding first :smile: