Master issue for documentation and examples

[andlabs]

libui is not yet well-documented. I started fixing this with utflib-and-attrstr, but we still have a while to go.

I have yet to find a documentation system I'm happy with. I am intending on writing my own, but am not sure when (if) that will happen again (since my first attempt didn't go smoothly; and even then I would need copyright clearance to continue working on it).

Ideally the documentation system should be similar to godoc with the addition of Markdown-formatted articles alongside the documentation and as Overview sections on each page.

The Go package ui already has somewhat better documentation I should try to integrate with libui somehow. A way to automatically propagate documentation to package ui would be a pipe dream.

The Go code is devoid of examples, and the API changes means old examples people still turn to don't work.

I'm not sure what problems people have with the documentation and examples that are there on both repositories, but that's also worth addressing.

I also need to figure out what to do about the wikis on GitHub.

[cody271]

Take another look at cldoc, it was actually the first thing I worked on if you recall. (#175)

I still think @parro-it's libui-node docs are the best place starting point for official libui docs. (#172)

[d3dave]

So far I have got along fine with the examples and comments in ui.h, but it would really help me now if someone explained uiDrawFillMode.

Thanks.

[andlabs]

I forget what my problem with cldoc was at first. My problem with the other tools that exist was their strict formatting rules. I originally wanted something like godoc but with Markdown pages. I wonder if having entirely separate documentation would work too... But sure, I can take a second look at cldoc.

@d3dave https://en.wikipedia.org/wiki/Nonzero-rule (though that might be a bit more advanced — example images on various drawing APIs might be a bit more clear)

[marcotrosi]

Hello awesome people,

is the tool for creating documentation now defined? can one contribute in writing documentation? are the fundamentals prepared for that?

thanks :-)

[andlabs]

I've taken a different approach entirely. Check the remodel branch. I'll be documenting functions as I move them back into the codebase. The documentation will be a bunch of static markdown pages with a TOC that will become a sidebar once all is said and done.

I really need to be better at communicating what my mental process is to everyone here so they can possibly help develop the branch, but first I wonder if I even know how or not

[franko]

I've taken a different approach entirely. Check the remodel branch. I'll be documenting functions as I move them back into the codebase. The documentation will be a bunch of static markdown pages with a TOC that will become a sidebar once all is said and done.

Hi Pietro, all,

I am personally following your work on libui and I hope you will succeed with the remodel branch.

Please don't hesitate to communicate in any way so that people can contribute to the project, if not with the code, at least with the documentation or other things. I think it would be beneficial for libui to gather some community around the project to infuse it with some additional momentum.

[rubyFeedback]

I think many people at this point are interested in libui. So far I think libui is not in a bad state at all; I think it is a great idea. The only slight bottleneck I see right now is in regards to documentation. I, and probably many other people, learn best from specific examples that work. I look at code, tweak and learn as I go. I can also use examples from other languages! But ultimately documentation is very important for newcomers. Perhaps the different languages can co-exchange examples, agree on "common example and documentation" infrastructure and such, so that they can all benefit from it, rather everyone doing their own thing in the long run. Or worded differently - I'd love to have a well-documented, organized documentation among all language bindings too. I don't think this should be solely up to Pietro alone but instead, the language bindings maintainers should get together and agree on improving the documentation, rather than merely seeing it as "I only care for this programming language and don't care about users of other programming languages at all whatsoever".

[rubyFeedback]

I think a community will form "on its own" when people notice that libui brings definitive advantages to the table. For example, I am also using ruby-gtk, and ruby-gtk is fine; but, libui is soooooooo much simpler for literally everyone, in particular distributing the code, so I would love to switch (or add support) for libui too, in the long run. And I am sure this will be valid for other users too, in other languages. It should be a larger community indeed, to avoid bottlenecks.