Improve reference documentation

[CzBiX]

trafficstars

At first, this is a great project, but the lacks of documentation makes users hard to get started.

What I am talking about isn't usage guide, but reference documentation. The most of classes and methods in openrndr are undocumented. As a user, I have to guess the API usage by variable name and even dig into codes inside.

Hope this issue can be solved gradually.

[edwinRNDR]

Hi @CzBiX, thank you and I absolutely agree that this is a problem. We have some plans lined up to improve the documentation, both for the guide and reference documentation. These plans include improvements to tooling and interfaces to the documentation.

The biggest challenge we have for reference documentation though is that we need to find some extra hands for writing and maintaining it. So consider this is a public plead :)

Thank you once again for bringing this to our attention!

[edwinRNDR]

@CzBiX do you have any specific parts of the API in mind? If I were to document parts of the API now, which parts should I document first?

[CzBiX]

As I think, we should first complete the description of class in org.openrndr and org.openrndr.draw. Which is the most/first used classes in a program. The description should contains what is it, when to use it, and how to use it(order by priority).

---

When I summited this issue, I was just switched from processing to openrndr, due to the performance issues in processing. I am not only satisfied with the performance of openrndr, but also like the Kotlin choice and the modern IDE support of it. When I try to load a jpg image from bytes, the ColorBuffer.fromBuffer I used was missing ImageFileFormat argument. It assume the bytes are PNG format and failed to load. So I dig into it, then I found that very basic class such as ColorType and ColorFormat are missing documentation. These classes are either undocumented or just repeated class name it self. Maybe I should contribute something too. 😄

[hamoid]

How does one contribute to such documentation?

[capital-G]

This gets more problematic since often the first google search results lead to a 404 now, e.g. openrndr fontimapmap returns this 404 as first result which is only availbale via archive.org Even an auto-generated empty skeleton of online API documentation would be helpful so at least I know if its not documented there it is not documented and I can stop searching for official documentation.

[hamoid]

Hi :) By searching for fontimagemap in https://api.openrndr.org/ (instead of using google) it finds this page: https://api.openrndr.org/openrndr-core/openrndr-core/org.openrndr.draw/-font-image-map/index.html in which one can click on types, functions and properties. But not many descriptions to read unfortunately.

I have no idea why google points to a different URL. Maybe the path changed recently?

So that means that there might be two issues: search engines pointing to outdated URLs plus api not very much documented.

Personally I have not used at all the api page. By reading the guide, exploring the source code with the IDE and asking in Slack it's been enough, but I agree that it would be better to have more docs.

ps. Now that I look at it, the archived version may be better because everything is visible by scrolling. In the new one one needs to click on Companion to find the two companion methods! Quite hidden.

[hamoid]

How does one contribute to such documentation?

Answering to my own question, I think it's something like this:

1. Fork this repo, clone your fork and get familiar with OPENRNDR.
2. Take a look at https://api.openrndr.org and find an undocumented section you know about.
3. Find the corresponding Kotlin file in this repo and add missing comments. Read about the suggested style.
4. To generate the api page locally to verify your newly added comments appear correctly, see this action. Currently on line 15 I see the following: ./gradlew dokkaHtmlMultiModule -Dorg.gradle.jvmargs=-Xmx1536M. Running that command on the command line creates the html documentation under the build/dokka/htmlMultiModule/ folder.
5. Open the index.html in that folder in your browser and if something is off, tweak your comments.
6. If you want to continue improving the api, go back to 3. Otherwise send Pull Requests from your fork.

[edwinRNDR]

Although I agree with the sentiment, there are no actionable items here and the issue is stale. Closing time.