Documentation contains C examples and incorrect descriptions
Nobody has claimed this yet.
- Dominant language
- Ada
- Stars
- 110
- Forks
- 22
- PR merge metrics
- No merged PRs in 30d
Description
I recently completed my first GtkAda application, and I'm delighted with it, but I had to give up on making sense of the documentation, because:
- The only examples I've seen in the examples seem to have been retained unchanged from Gtk's C examples. Even someone familiar with C would have difficulty making sense of them, because GtkAda has a different interface than Gtk: many similarly-named functions act differently, and some C functions don't appear in the Ada version, and vice versa.
- Some functions are documented incorrectly. For instance, the
Nextfunction on aTree_Iteris said to returnTrueorFalse, but it returns a pointer instead, and the apparent (and apparently undocumented) design is to compare toNull_Iter. (I might be remembering the name wrong.)
It would be OK to submit patches to change this, correct? If so, I'll do this in reference to this issue. I just want to make sure there wasn't a deliberate decision to retain this.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the existing examples and the documentation for Tree_Iter.Next, which the issue identifies as problematic. Review whether the examples reflect GtkAda rather than Gtk, and verify the documented return behavior against the actual interface. Done means adding Ada-specific examples and correcting inaccurate descriptions, including the Next result and Null_Iter comparison.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100