search

brgl / libgpiod

This is a mirror of the original repository over at kernel.org. This github page is for discussions and issue reporting only. PRs can be discussed here but the patches need to go through the linux-gpio mailing list.
https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
Other
306 stars 106 forks source link

Documentation issues #63

Closed Shulyaka closed 7 months ago

Shulyaka commented 7 months ago

The documentation is very incomplete. Not only it lacks some quick start guide (e.g. get the chip - get the line info - create a line request, etc) or a migration guide from 1.x versions, but also some of the functions are missing. For the example, check the Line info section. There are number of function listed that operate on struct gpiod_line_info *, but not a single function to obtain this struct. The header file has the gpiod_chip_get_line_info function but it is not documented.

As a result, it is virtually impossible to deduce from the documentation how the API should be used.

brgl commented 7 months ago

Yeah, it's unfortunate that a project I'm developing in my free time and which made me so far precisely 0€ does not offer documentation that's on par with commercial software. Feel free to improve the docs and send the patches to the linux-gpio mailing list, I'll happily accept them.

The header file has the gpiod_chip_get_line_info function but it is not documented.

Your very link points to the documentation, I'm not sure what you mean.

Shulyaka commented 7 months ago

Yeah, it's unfortunate that a project I'm developing in my free time and which made me so far precisely 0€ does not offer documentation that's on par with commercial software.

Sorry for the miscommunication, I didn't mean to offense, you are doing a great job and it's a great project. But there is a room for improvement, so I opened the issue to help with that.

Your very link points to the documentation, I'm not sure what you mean.

Not exactly. My link points to the header file, but the function is missing in the doxygen documentation.

warthog618 commented 7 months ago

Your very link points to the documentation, I'm not sure what you mean.

Not exactly. My link points to the header file, but the function is missing in the doxygen documentation.

Note sure what you mean - it is there in the doxygen documentation. It may be brief, and perhaps you can suggest how to expand it or even provide a patch, but it is there. Btw, there are also examples provided for many common use cases, including getting line info.

Shulyaka commented 7 months ago

Note sure what you mean - it is there in the doxygen documentation.

You are right, it is not missing, it is just in another section, that's why I couldn't find it!

You are also right, the examples are very helpful.

It is still hard to read the documentation though, but now I realize that it might be subjective, so I chose to close the issue. Thank you!