Skip to content

Commit

Permalink
docs: fix sphinx-apidoc errors and warnings
Browse files Browse the repository at this point in the history
  • Loading branch information
@antoinevg
antoinevg committed Feb 26, 2024
1 parent be663ee commit bb1a1d5
Show file tree
Hide file tree
Showing 7 changed files with 172 additions and 133 deletions.
55 changes: 28 additions & 27 deletions facedancer/backends/greathost.py
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# GreatDancerHostApp.py
#
# Host support for GreatFET-base devices
# This file is part of Facedancer.
#
""" Host support for GreatFET-base devices. """

import sys
import time
Expand Down Expand Up @@ -255,24 +256,22 @@ def set_up_endpoint(self, endpoint_address_or_object, endpoint_type=None, max_pa
Sets up an endpoint for use. Can be used to initialize an endpoint or to update
its parameters. Two forms exist:
endpoint_object -- a USBEndpoint object with the parameters to be populated
Parameters:
endpoint_object -- a USBEndpoint object with the parameters to be populated
or
endpoint_address -- the address of the endpoint to be setup; including the direction bit
endpoint_type -- one of the ENDPOINT_TYPE constants that specifies the transfer mode on
the endpoint_address
max_packet_size -- the maximum packet size to be communicated on the given endpoint
device_address -- the address of the device to be communicated with; if not provided,
the last address will be used
endpoint_speed -- the speed of the packets to be communicated on the endpoint; should be a
DEVICE_SPEED_* constant; if not provided, the last device's speed will be used
handle_data_toggle -- true iff the hardware should automatically handle selection of data
packet PIDs
is_control_endpoint -- true iff the given packet is a for a control endpoint
TODO: eventually support hubs / more than one device?
Parameters:
endpoint_address -- the address of the endpoint to be setup; including the direction bit
endpoint_type -- one of the ENDPOINT_TYPE constants that specifies the transfer mode on
the endpoint_address
max_packet_size -- the maximum packet size to be communicated on the given endpoint
device_address -- the address of the device to be communicated with; if not provided, the last
address will be used.
endpoint_speed -- the speed of the packets to be communicated on the endpoint; should be a
DEVICE_SPEED_* constant; if not provided, the last device's speed will be used.
handle_data_toggle -- true iff the hardware should automatically handle selection of data packet PIDs
is_control_endpoint -- true iff the given packet is a for a control endpoint
"""

if isinstance(endpoint_address_or_object, USBEndpoint):
Expand Down Expand Up @@ -336,12 +335,13 @@ def send_on_endpoint(self, endpoint_number, data, is_setup=False,
"""
Sends a block of data on the provided endpoints.
endpoint_number -- The endpoint number on which to send.
data -- The data to be transmitted.
is_setup -- True iff this transfer should begin with a SETUP token.
blocking -- True iff this transaction should wait for the transaction to complete.
data_packet_pid -- The data packet PID to use (1 or 0). Ignored if the endpoint is set to automatically
alternate data PIDs.
Parameters:
endpoint_number -- The endpoint number on which to send.
data -- The data to be transmitted.
is_setup -- True iff this transfer should begin with a SETUP token.
blocking -- True iff this transaction should wait for the transaction to complete.
data_packet_pid -- The data packet PID to use (1 or 0). Ignored if the endpoint is set to automatically
alternate data PIDs.
raises an IOError on a communications error or stall
"""
Expand Down Expand Up @@ -378,10 +378,11 @@ def read_from_endpoint(self, endpoint_number, expected_read_size=64, data_packet
"""
Sends a block of data on the provided endpoints.
endpoint_number -- The endpoint number on which to send.
expected_read_size -- The expected amount of data to be read.
data_packet_pid -- The data packet PID to use (1 or 0).
Ignored if the endpoint is set to automatically alternate data PIDs.
Parameters:
endpoint_number -- The endpoint number on which to send.
expected_read_size -- The expected amount of data to be read.
data_packet_pid -- The data packet PID to use (1 or 0).
Ignored if the endpoint is set to automatically alternate data PIDs.
raises an IOError on a communications error or stall
"""
Expand Down
99 changes: 56 additions & 43 deletions facedancer/backends/libusbhost.py
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# LibUSBHostApp.py
#
# Host support for accessing libusb with a FaceDancer-like syntax.
# This file is part of Facedancer.
#
""" Host support for accessing libusb with a Facedancer-like syntax. """

import sys
import time
Expand All @@ -15,6 +16,7 @@ class LibUSBHostApp(FacedancerUSBHost):
"""
Class that represents a libusb-based USB host.
"""

app_name = "LibUSB Host"

@classmethod
Expand Down Expand Up @@ -87,9 +89,10 @@ def bus_reset(self, delay=0):
"""
Issues a "bus reset", requesting that the downstream device reset itself.
Parameters:
delay -- The amount of time, in seconds, to wait before or after the
reset request. To be compliant, this should be omitted, or set
to 0.1s.
reset request. To be compliant, this should be omitted, or set
to 0.1s.
"""

# Note: we need to wait a reset delay before and after the bus reset.
Expand All @@ -102,8 +105,9 @@ def bus_reset(self, delay=0):
def current_device_speed(self, as_string=False):
""" Returns the speed of the connected device
as_string -- If true, returns the speed as a string for printing; otherwise
returns a DEVICE_SPEED_* constant.
Parameters:
as_string -- If true, returns the speed as a string for printing; otherwise returns
a DEVICE_SPEED_* constant.
"""
return self.device.speed

Expand All @@ -112,7 +116,7 @@ def current_line_state(self, as_string=False):
""" Returns the current state of the USB differential pair
as_string -- If true, returns the speed as a string for printing; otherwise
returns a LINE_STATE_* constant.
returns a LINE_STATE_* constant.
"""
return None

Expand All @@ -139,25 +143,26 @@ def set_up_endpoint(self, endpoint_address_or_object, endpoint_type=None, max_pa
Sets up an endpoint for use. Can be used to initialize an endpoint or to update
its parameters. Two forms exist:
endpoint_object -- a USBEndpoint object with the parameters to be populated
Parameters:
endpoint_object -- a USBEndpoint object with the parameters to be populated
or
endpoint_address -- the address of the endpoint to be setup; including the direction bit
endpoint_type -- one of the ENDPOINT_TYPE constants that specifies the transfer mode on
the endpoint_address
max_packet_size -- the maximum packet size to be communicated on the given endpoint
Parameters:
endpoint_address -- the address of the endpoint to be setup; including the direction bit
endpoint_type -- one of the ENDPOINT_TYPE constants that specifies the transfer mode on
the endpoint_address
max_packet_size -- the maximum packet size to be communicated on the given endpoint
device_address -- the address of the device to be communicated with; if not provided, the
last address will be used
endpoint_speed -- the speed of the packets to be communicated on the endpoint; should be a
DEVICE_SPEED_* constant; if not provided, the last device's speed will be used.
handle_data_toggle -- true iff the hardware should automatically handle selection of data packet PIDs
is_control_endpoint -- true iff the given packet is a for a control endpoint
"""

device_address -- the address of the device to be communicated with; if not provided,
the last address will be used
endpoint_speed -- the speed of the packets to be communicated on the endpoint; should be a
DEVICE_SPEED_* constant; if not provided, the last device's speed will be used
handle_data_toggle -- true iff the hardware should automatically handle selection of data
packet PIDs
is_control_endpoint -- true iff the given packet is a for a control endpoint
# TODO: eventually support hubs / more than one device?

TODO: eventually support hubs / more than one device?
"""
pass


Expand All @@ -173,12 +178,13 @@ def send_on_endpoint(self, endpoint_number, data, is_setup=False,
"""
Sends a block of data on the provided endpoints.
endpoint_number -- The endpoint number on which to send.
data -- The data to be transmitted.
is_setup -- True iff this transfer should begin with a SETUP token.
blocking -- True iff this transaction should wait for the transaction to complete.
data_packet_pid -- The data packet PID to use (1 or 0). Ignored if the endpoint is set to automatically
alternate data PIDs.
Parameters:
endpoint_number -- The endpoint number on which to send.
data -- The data to be transmitted.
is_setup -- True iff this transfer should begin with a SETUP token.
blocking -- True iff this transaction should wait for the transaction to complete.
data_packet_pid -- The data packet PID to use (1 or 0). Ignored if the endpoint is set to automatically
alternate data PIDs.
raises an IOError on a communications error or stall
"""
Expand All @@ -189,10 +195,11 @@ def read_from_endpoint(self, endpoint_number, expected_read_size=64, data_packet
"""
Sends a block of data on the provided endpoints.
endpoint_number -- The endpoint number on which to send.
expected_read_size -- The expected amount of data to be read.
data_packet_pid -- The data packet PID to use (1 or 0).
Ignored if the endpoint is set to automatically alternate data PIDs.
Parameters:
endpoint_number -- The endpoint number on which to send.
expected_read_size -- The expected amount of data to be read.
data_packet_pid -- The data packet PID to use (1 or 0).
Ignored if the endpoint is set to automatically alternate data PIDs.
raises an IOError on a communications error or stall
"""
Expand All @@ -203,12 +210,15 @@ def read_from_endpoint(self, endpoint_number, expected_read_size=64, data_packet
def control_request_in(self, request_type, recipient, request, value=0, index=0, length=0):
""" Performs an IN control request.
request_type -- Determines if this is a standard, class, or vendor request. Accepts a REQUEST_TYPE_* constant.
recipient -- Determines the context in which this command is interpreted. Accepts a REQUEST_RECIPIENT_* constant.
request -- The request number to be performed.
value, index -- The standard USB request arguments, to be included in the setup packet. Their meaning varies
depending on the request.
length -- The maximum length of data expected in response, or 0 if we don't expect any data back.
Parameters:
request_type -- Determines if this is a standard, class, or vendor request. Accepts a
REQUEST_TYPE_* constant.
recipient -- Determines the context in which this command is interpreted. Accepts a
REQUEST_RECIPIENT_* constant.
request -- The request number to be performed.
value, index -- The standard USB request arguments, to be included in the setup packet.
Their meaning varies depending on the request.
length -- The maximum length of data expected in response, or 0 if we don't expect any data back.
"""

request_type = self._build_request_type(True, request_type, recipient)
Expand All @@ -220,12 +230,15 @@ def control_request_in(self, request_type, recipient, request, value=0, index=0,
def control_request_out(self, request_type, recipient, request, value=0, index=0, data=[]):
""" Performs an OUT control request.
request_type -- Determines if this is a standard, class, or vendor request. Accepts a REQUEST_TYPE_* constant.
recipient -- Determines the context in which this command is interpreted. Accepts a REQUEST_RECIPIENT_* constant.
request -- The request number to be performed.
value, index -- The standard USB request arguments, to be included in the setup packet. Their meaning varies
depending on the request.
data -- The data to be transmitted with this control request.
Parameters:
request_type -- Determines if this is a standard, class, or vendor request. Accepts a
REQUEST_TYPE_* constant.
recipient -- Determines the context in which this command is interpreted. Accepts a
REQUEST_RECIPIENT_* constant.
request -- The request number to be performed.
value, index -- The standard USB request arguments, to be included in the setup packet. Their meaning
varies depending on the request.
data -- The data to be transmitted with this control request.
"""

request_type = self._build_request_type(True, request_type, recipient)
Expand Down
9 changes: 5 additions & 4 deletions facedancer/configuration.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,7 @@ class USBConfiguration(USBDescribable, AutoInstantiable, USBRequestHandler):
Fields:
number -- The configuration's number; one-indexed.
configuration_string -- A string describing the configuration; or None if not provided.
max_power -- The maximum power expected to be drawn by the device when using
this interface, in mA. Typically 500mA, for maximum possible.
max_power -- The maximum power expected to be drawn by the device when using this interface, in mA. Typically 500mA, for maximum possible.
supports_remote_wakeup -- True iff this device should be able to wake the host from suspend.
"""

Expand All @@ -51,7 +50,8 @@ def from_binary_descriptor(cls, data):
Generates a new USBConfiguration object from a configuration descriptor,
handling any attached subordinate descriptors.
data: The raw bytes for the descriptor to be parsed.
Parameters:
data: The raw bytes for the descriptor to be parsed.
"""

length = data[0]
Expand Down Expand Up @@ -81,7 +81,8 @@ def _parse_subordinate_descriptors(cls, data):
"""
Generates descriptor objects from the list of subordinate descriptors.
data: The raw bytes for the descriptor to be parsed.
Parameters:
data: The raw bytes for the descriptor to be parsed.
"""

# TODO: handle recieving interfaces out of order?
Expand Down
Loading

0 comments on commit bb1a1d5

Please sign in to comment.