Skip to content

Commit 4de9528

Browse files
committed
crash.util: add more documentation
No code changes. This just updates the API documentation for crash.util. Signed-off-by: Jeff Mahoney <jeffm@suse.com>
1 parent 0bc0a30 commit 4de9528

1 file changed

Lines changed: 22 additions & 3 deletions

File tree

‎crash/util/__init__.py‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,10 @@ def container_of(val, gdbtype, member):
8282
Args:
8383
val (gdb.Value): The value to be converted. It can refer to an
8484
allocated structure or a pointer.
85-
gdbtype (gdb.Type): The type of the object that will be generated
86-
member (str): The name of the member in the target struct that
87-
contains `val`.
85+
gdbtype (gdb.Type, gdb.Value, str, gdb.Symbol):
86+
The type of the object that will be generated
87+
member (str):
88+
The name of the member in the target struct that contains `val`.
8889
8990
Returns:
9091
gdb.Value<gdbtype>: The converted object, of the type specified by
@@ -185,6 +186,7 @@ def resolve_type(val):
185186
186187
Raises:
187188
TypeError: The object type of val is not valid
189+
MissingTypeError: could not resolve the type from string argument
188190
"""
189191
if isinstance(val, gdb.Type):
190192
gdbtype = val
@@ -337,6 +339,8 @@ def safe_lookup_type(name, block=None):
337339
338340
Args:
339341
name (str): The name of the type to look up
342+
block (gdb.Block, optional, default=None):
343+
The block to use to resolve the type
340344
341345
Returns:
342346
gdb.Type for requested type or None if it could not be found
@@ -352,6 +356,9 @@ def array_size(value):
352356
353357
Args:
354358
value (gdb.Value): The array to size
359+
360+
Returns:
361+
int: The number of elements in the array
355362
"""
356363
return value.type.sizeof // value[0].type.sizeof
357364

@@ -366,6 +373,9 @@ def get_typed_pointer(val, gdbtype):
366373
367374
Returns:
368375
gdb.Value: The casted pointer of the requested type
376+
377+
Raises:
378+
TypeError: string value for val does not describe a hex address
369379
"""
370380
if gdbtype.code != gdb.TYPE_CODE_PTR:
371381
gdbtype = gdbtype.pointer()
@@ -386,6 +396,15 @@ def get_typed_pointer(val, gdbtype):
386396
return val
387397

388398
def array_for_each(value):
399+
"""
400+
Yields each element in an array separately
401+
402+
Args:
403+
value (gdb.Value): The array to iterate
404+
405+
Yields:
406+
gdb.Value: One element in the array at a time
407+
"""
389408
size = array_size(value)
390409
for i in range(array_size(value)):
391410
yield value[i]

0 commit comments

Comments
 (0)