[PATCH v7 6/7] wpa_supplicant: doc: Replace Native Part 1.

[Jouni Malinen]

On Sat, Sep 18, 2021 at 11:24:31PM -0700, Arowa Suliman wrote:
> Replaced the word Native with more inclusive words such as built-in.

While I'm not necessarily against some of these changes, I'm not
convinced there is strong need to replace terms like "native interface"
and I don't really like to make such changes just to get rid of the word
"native" if the new version is inaccurate or more difficult to
understand.

> diff --git a/doc/code_structure.doxygen b/doc/code_structure.doxygen
> @@ -62,7 +62,7 @@ with with hostapd. The following C files are currently used:
>  \ref l2_packet.h, \ref l2_packet_linux.c, and \ref l2_packet_pcap.c
> -	Layer 2 (link) access wrapper (includes native Linux implementation
> +	Layer 2 (link) access wrapper (includes Linux packet socket
>  	and wrappers for libdnet/libpcap). A new l2_packet implementation

This feels fine since it is a more specific reference to what this is
talking about.

> diff --git a/doc/driver_wrapper.doxygen b/doc/driver_wrapper.doxygen
> @@ -27,10 +27,10 @@ documented in \ref driver.h. In addition, a pointer to the 'struct
>  When porting to other operating systems, the driver wrapper should be
> -modified to use the native interface of the target OS. It is possible
> -that some extra requirements for the interface between the driver
> -wrapper and generic wpa_supplicant code are discovered during porting
> -to a new operating system. These will be addressed on case by case
> +modified to use the direct interface of the target OS (No extra adoption
> +layer). It is possible that some extra requirements for the interface between
> +the driver wrapper and generic wpa_supplicant code are discovered during
> +porting to a new operating system. These will be addressed on case by case

This looks more difficult to understand since "native interface" is the
technical term used for referring to the interface provided by a
component like the operating system. Trying to replace that with "direct
interface" and a parenthetical to explain the uncommon term for that
does not exactly improve readability here..

> diff --git a/doc/p2p.doxygen b/doc/p2p.doxygen
> @@ -274,8 +274,8 @@ for removing the group interface for the failed group.
>  P2P protocol includes service discovery functionality that can be used
>  to discover which services are provided by the peers before forming a
>  group. This leverages the Generic Advertisement Service (GAS) protocol
> -from IEEE 802.11u and P2P vendor-specific contents inside the Native
> -GAS messages.
> +from IEEE 802.11u and P2P vendor-specific contents inside the GAS
> +messages.

This is fine since I don't even remember where that previously used term
came from.

> diff --git a/doc/porting.doxygen b/doc/porting.doxygen
> @@ -21,7 +21,8 @@ most targets. However, couple of additional functions that are common
>  on modern UNIX systems are used. Number of these are listed with
>  prototypes in \ref common.h (the \verbatim #ifdef CONFIG_ANSI_C_EXTRA \endverbatim
>  block). These functions may need to be implemented or at least defined
> -as macros to native functions in the target OS or C library.
> +as macros to direct functions in the target OS (No extra adoption layer) or C
> +library.

This is in the same category with "native interface". Use of an uncommon
term that requires a parenthetical to explain what is meant here is not
a good approach.

> diff --git a/wpa_supplicant/ChangeLog b/wpa_supplicant/ChangeLog
> @@ -1864,7 +1864,7 @@ ChangeLog for wpa_supplicant
>  	* l2_packet_linux: use socket type SOCK_DGRAM instead of SOCK_RAW for
>  	  PF_PACKET in order to prepare for network devices that do not use
> -	  Ethernet headers (e.g., network stack with native IEEE 802.11 frames)
> +	  Ethernet headers (e.g., network stack that includes IEEE 802.11 headers)

This feels a bit borderline regarding clarity due to the use of native
802.11 frames in multiple different interfaces and loss of that common
term. Technically, it feels incorrect to say that a network stack
includes a header. Maybe something like "networks stacks that include
the IEEE 802.11 header in the frames" would be accurate.

-- 
Jouni Malinen                                            PGP id EFC895FA