C libUART - Recommendations for improvement on FreeBSD

K

Krotti83

I created a cross platform library for accessing the UART (RS232) interface. Currently targeting Linux, Windows and FreeBSD.
In my initialization functions from the library I test first if an user is in the group dialer to use the call-out ports, which are documented
here. For communication and setup I use the POSIX functions from termios currently.

Are there some recommendations to use the UART interfaces a better way? Should I use the call-in ports instead?

The current full code can be found under https://github.com/Krotti83/libUART
 
While your readme file has lots of technical details, it is missing the single most important thing: What is the purpose of the library on POSIX systems (such as Linux and Windows)? What are the requirements? What operations and settings need to be supported? You are mostly providing thin wrappers around POSIX standard library and termios functions, why not let the user call those directly? Being POSIX, they should be highly compatible on all systems.
 
FWIW, don't make library functions UID specific! Let the kernel level device protections do their stuff. Don't set policy in your tools, but provide generic protection-abstract tools that let the end user decide how they will use them. The device files have standard filemode protections assigned to them. Simply error out if the current user doesn't have permission, but don't set policy on what UID/GID they need to be.
 
ralphbsz said:
While your readme file has lots of technical details, it is missing the single most important thing: What is the purpose of the library on POSIX systems (such as Linux and Windows)? What are the requirements? What operations and settings need to be supported? You are mostly providing thin wrappers around POSIX standard library and termios functions, why not let the user call those directly? Being POSIX, they should be highly compatible on all systems.
Click to expand...

I'm only responding here because this is a current pet peave of mine: really lousy technical documentation has become mainstream and even ACCEPTED! For ANY technical documentation to pass my review it needs four things.
1) identify and be focused to the specific target audience
2) provide an architectural process flow that teaches the process and meaning behind it
3) provide a comprehensive reference guide
4) support with examples

Documentation by example only is NEVER adequate...and no, reading the code does not make it obvious

;)
 
You must log in or register to reply here.
Back
Top