Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2025-02-20 17:20:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1749473 - fix docstring for autodoc r=firefox-source-docs-reviewers,sylvestre

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D171436
This commit is contained in:
ogiorgis 2023-03-03 09:37:42 +00:00
parent 5a2855fc5e
commit bf64e21d0b
34 changed files with 162 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/config.yml
View File

@ -111,4 +111,4 @@ redirects:
fatal warnings:
- "WARNING: '([^']*)' reference target not found:((?!.rst).)*$"
max_num_warnings: 6300
max_num_warnings: 6220

6
python/mach/mach/decorators.py
View File

@ -177,6 +177,8 @@ class Command(object):
For example:
.. code-block:: python
@Command('foo', category='misc', description='Run the foo action')
def foo(self, command_context):
pass
@ -255,6 +257,8 @@ class CommandArgument(object):
For example:
.. code-block:: python
@Command('foo', help='Run the foo action')
@CommandArgument('-b', '--bar', action='store_true', default=False,
help='Enable bar mode.')
@ -290,6 +294,8 @@ class CommandArgumentGroup(object):
For example:
.. code-block: python
@Command('foo', helps='Run the foo action')
@CommandArgumentGroup('group1')
@CommandArgument('-b', '--bar', group='group1', action='store_true',

10
python/mach/mach/main.py
View File

@ -36,8 +36,8 @@ from .telemetry import create_telemetry_from_environment, report_invocation_metr
from .util import UserError, setenv
SUGGEST_MACH_BUSTED_TEMPLATE = r"""
You can invoke |./mach busted| to check if this issue is already on file. If it
isn't, please use |./mach busted file %s| to report it. If |./mach busted| is
You can invoke ``./mach busted`` to check if this issue is already on file. If it
isn't, please use ``./mach busted file %s`` to report it. If ``./mach busted`` is
misbehaving, you can also inspect the dependencies of bug 1543241.
""".lstrip()
@ -82,13 +82,13 @@ a bug in the called code itself or in the way that mach is calling it.
NO_COMMAND_ERROR = r"""
It looks like you tried to run mach without a command.
Run |mach help| to show a list of commands.
Run ``mach help`` to show a list of commands.
""".lstrip()
UNKNOWN_COMMAND_ERROR = r"""
It looks like you are trying to %s an unknown mach command: %s
%s
Run |mach help| to show a list of commands.
Run ``mach help`` to show a list of commands.
""".lstrip()
SUGGESTED_COMMANDS_MESSAGE = r"""
@ -195,7 +195,7 @@ class Mach(object):
populate_context_handler -- If defined, it must be a callable. The
callable signature is the following:
populate_context_handler(key=None)
populate_context_handler(key=None)
It acts as a fallback getter for the mach.base.CommandContext
instance.
This allows to augment the context instance with arbitrary data

9
python/mach/mach/mixin/logging.py
View File

@ -42,10 +42,11 @@ class LoggingMixin(object):
performed by calling format() on this string, feeding into it the dict
of attributes constituting the event.
Example Usage
-------------
Example Usage:
self.log(logging.DEBUG, 'login', {'username': 'johndoe'},
'User login: {username}')
.. code-block:: python
self.log(logging.DEBUG, 'login', {'username': 'johndoe'},
'User login: {username}')
"""
self._logger.log(level, format_str, extra={"action": action, "params": params})

11
python/mach/mach/site.py
View File

@ -444,13 +444,16 @@ class CommandSiteManager:
used standalone to invoke a script).
A few notes:
* The command environment always inherits Mach's import scope. This is because
"unloading" packages in Python is error-prone, so in-process activations will always
carry Mach's dependencies along with it. Accordingly, compatibility between each
command environment and the Mach environment must be maintained
* The command environment always inherits Mach's import scope. This is
because "unloading" packages in Python is error-prone, so in-process activations
will always carry Mach's dependencies along with it. Accordingly, compatibility
between each command environment and the Mach environment must be maintained
* Unlike the Mach environment, command environments *always* have an associated
physical virtualenv on-disk. This is because some commands invoke child Python
processes, and that child process should have the same import scope.
"""
def __init__(

4
python/mozbuild/mozbuild/action/buildlist.py
View File

@ -16,8 +16,8 @@ from mozbuild.util import ensureParentDir, lock_file
def addEntriesToListFile(listFile, entries):
"""Given a file |listFile| containing one entry per line,
add each entry in |entries| to the file, unless it is already
"""Given a file ``listFile`` containing one entry per line,
add each entry in ``entries`` to the file, unless it is already
present."""
ensureParentDir(listFile)
lock = lock_file(listFile + ".lck")

13
python/mozbuild/mozbuild/action/process_define_files.py
View File

@ -15,13 +15,14 @@ from mozbuild.backend.configenvironment import PartialConfigEnvironment
def process_define_file(output, input):
"""Creates the given config header. A config header is generated by
taking the corresponding source file and replacing some #define/#undef
taking the corresponding source file and replacing some *#define/#undef*
occurences:
"#undef NAME" is turned into "#define NAME VALUE"
"#define NAME" is unchanged
"#define NAME ORIGINAL_VALUE" is turned into "#define NAME VALUE"
"#undef UNKNOWN_NAME" is turned into "/* #undef UNKNOWN_NAME */"
Whitespaces are preserved.
- "#undef NAME" is turned into "#define NAME VALUE"
- "#define NAME" is unchanged
- "#define NAME ORIGINAL_VALUE" is turned into "#define NAME VALUE"
- "#undef UNKNOWN_NAME" is turned into "/* #undef UNKNOWN_NAME */"
- Whitespaces are preserved.
As a special rule, "#undef ALLDEFINES" is turned into "#define NAME
VALUE" for all the defined variables.

11
python/mozbuild/mozbuild/artifact_cache.py
View File

@ -61,11 +61,14 @@ class ArtifactPersistLimit(dlmanager.PersistLimit):
After a download finishes, the newly downloaded file is registered, and the
oldest files registered to the PersistLimit instance are removed depending
on the size and file limits it's configured for.
This is all good, but there are a few tweaks we want here:
- We have pickle files in the cache directory that we don't want purged.
- Files that were just downloaded in the same session shouldn't be purged.
(if for some reason we end up downloading more than the default max size,
we don't want the files to be purged)
- We have pickle files in the cache directory that we don't want purged.
- Files that were just downloaded in the same session shouldn't be
purged. (if for some reason we end up downloading more than the default
max size, we don't want the files to be purged)
To achieve this, this subclass of PersistLimit inhibits the register_file
method for pickle files and tracks what files were downloaded in the same
session to avoid removing them.

4
python/mozbuild/mozbuild/artifact_commands.py
View File

@ -64,10 +64,10 @@ class ArtifactSubCommand(SubCommand):
def artifact(command_context):
"""Download, cache, and install pre-built binary artifacts to build Firefox.
Use |mach build| as normal to freshen your installed binary libraries:
Use ``mach build`` as normal to freshen your installed binary libraries:
artifact builds automatically download, cache, and install binary
artifacts from Mozilla automation, replacing whatever may be in your
object directory. Use |mach artifact last| to see what binary artifacts
object directory. Use ``mach artifact last`` to see what binary artifacts
were last used.
Never build libxul again!

2
python/mozbuild/mozbuild/artifacts.py
View File

@ -27,7 +27,7 @@ This module performs the following steps:
so we don't have to mount DMG files frequently.
This module requires certain modules be importable from the ambient Python
environment. |mach artifact| ensures these modules are available, but other
environment. ``mach artifact`` ensures these modules are available, but other
consumers will need to arrange this themselves.
"""

2
python/mozbuild/mozbuild/backend/base.py
View File

@ -255,7 +255,7 @@ class BuildBackend(LoggingMixin):
status value of a subprocess, where 0 denotes success and any
other value is an error code.
If an exception is raised, |mach build| will fail with a
If an exception is raised, ``mach build`` will fail with a
non-zero exit code.
"""
self._write_purgecaches(config)

15
python/mozbuild/mozbuild/backend/configenvironment.py
View File

@ -88,8 +88,7 @@ class ConfigEnvironment(object):
Creating a ConfigEnvironment requires a few arguments:
- topsrcdir and topobjdir are, respectively, the top source and
the top object directory.
- defines is a dict filled from AC_DEFINE and AC_DEFINE_UNQUOTED in
autoconf.
- defines is a dict filled from AC_DEFINE and AC_DEFINE_UNQUOTED in autoconf.
- substs is a dict filled from AC_SUBST in autoconf.
ConfigEnvironment automatically defines one additional substs variable
@ -97,15 +96,15 @@ class ConfigEnvironment(object):
- ACDEFINES contains the defines in the form -DNAME=VALUE, for use on
preprocessor command lines. The order in which defines were given
when creating the ConfigEnvironment is preserved.
and two other additional subst variables from all the other substs:
- ALLSUBSTS contains the substs in the form NAME = VALUE, in sorted
order, for use in autoconf.mk. It includes ACDEFINES
order, for use in autoconf.mk. It includes ACDEFINES.
Only substs with a VALUE are included, such that the resulting file
doesn't change when new empty substs are added.
This results in less invalidation of build dependencies in the case
of autoconf.mk..
- ALLEMPTYSUBSTS contains the substs with an empty value, in the form
NAME =.
- ALLEMPTYSUBSTS contains the substs with an empty value, in the form NAME =.
ConfigEnvironment expects a "top_srcdir" subst to be set with the top
source directory, in msys format on windows. It is used to derive a
@ -314,14 +313,16 @@ class PartialConfigEnvironment(object):
The PartialConfigEnvironment automatically defines one additional subst variable
from all the defines:
- ACDEFINES contains the defines in the form -DNAME=VALUE, for use on
preprocessor command lines. The order in which defines were given
when creating the ConfigEnvironment is preserved.
and one additional define from all the defines as a dictionary:
- ALLDEFINES contains all of the global defines as a dictionary. This is
intended to be used instead of the defines structure from config.status so
that scripts can depend directly on its value.
intended to be used instead of the defines structure from config.status so
that scripts can depend directly on its value.
"""
def __init__(self, topobjdir):

1
python/mozbuild/mozbuild/backend/recursivemake.py
View File

@ -251,6 +251,7 @@ class RecursiveMakeTraversal(object):
filter is a function with the following signature:
def filter(current, subdirs)
where current is the directory being traversed, and subdirs the
SubDirectories instance corresponding to it.
The filter function returns a tuple (filtered_current, filtered_parallel,

4
python/mozbuild/mozbuild/faster_daemon.py
View File

@ -3,8 +3,8 @@
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
"""
Use pywatchman to watch source directories and perform partial |mach
build faster| builds.
Use pywatchman to watch source directories and perform partial
``mach build faster`` builds.
"""
import datetime

12
python/mozbuild/mozbuild/frontend/context.py
View File

@ -870,7 +870,7 @@ class Path(six.with_metaclass(PathMeta, ContextDerivedValue, six.text_type)):
return self
def join(self, *p):
"""ContextDerived equivalent of mozpath.join(self, *p), returning a
"""ContextDerived equivalent of `mozpath.join(self, *p)`, returning a
new Path instance.
"""
return Path(self.context, mozpath.join(self, *p))
@ -1034,10 +1034,12 @@ def ContextDerivedTypedRecord(*fields):
This API is extremely similar to the TypedNamedTuple API,
except that properties may be mutated. This supports syntax like:
VARIABLE_NAME.property += [
'item1',
'item2',
]
.. code-block:: python
VARIABLE_NAME.property += [
'item1',
'item2',
]
"""
class _TypedRecord(ContextDerivedValue):

2
python/mozbuild/mozbuild/frontend/reader.py
View File

@ -1066,7 +1066,7 @@ class BuildReader(object):
This starts with a single mozbuild file, executes it, and descends into
other referenced files per our traversal logic.
The traversal logic is to iterate over the *DIRS variables, treating
The traversal logic is to iterate over the ``*DIRS`` variables, treating
each element as a relative directory path. For each encountered
directory, we will open the moz.build file located in that
directory in a new Sandbox and process it.

4
python/mozbuild/mozbuild/makeutil.py
View File

@ -99,9 +99,7 @@ class _SimpleOrderedSet(object):
class Rule(object):
"""Class handling simple rules in the form:
target1 target2 ... : dep1 dep2 ...
command1
command2
...
command1 command2 ...
"""
def __init__(self, targets=()):

2
python/mozbuild/mozbuild/test/backend/test_recursivemake.py
View File

@ -994,7 +994,7 @@ class TestRecursiveMakeBackend(BackendTester):
self.assertEqual(lines, expected)
def test_rust_programs(self):
"""Test that {HOST_,}RUST_PROGRAMS are written to backend.mk correctly."""
"""Test that `{HOST_,}RUST_PROGRAMS` are written to backend.mk correctly."""
env = self._consume("rust-programs", RecursiveMakeBackend)
backend_path = mozpath.join(env.topobjdir, "code/backend.mk")

3
python/mozbuild/mozbuild/util.py
View File

@ -707,6 +707,9 @@ def StrictOrderingOnAppendListWithFlagsFactory(flags):
the flag names, and values the type used for the value of that flag.
Example:
.. code-block:: python
FooList = StrictOrderingOnAppendListWithFlagsFactory({
'foo': bool, 'bar': unicode
})

65
python/mozbuild/mozbuild/vendor/rewrite_mozbuild.py vendored
View File

@ -13,10 +13,11 @@ Problem:
be able to effectively update a library automatically and send useful try runs in.
So far, it has been difficult to do that.
Why:
Some files need to go into UNIFIED_SOURCES vs SOURCES
Some files are os-specific, and need to go into per-OS conditionals
Some files are both UNIFIED_SOURCES/SOURCES sensitive and OS-specific.
- Some files need to go into UNIFIED_SOURCES vs SOURCES
- Some files are os-specific, and need to go into per-OS conditionals
- Some files are both UNIFIED_SOURCES/SOURCES sensitive and OS-specific.
Proposal:
Design an algorithm that maps a third party library file to a suspected moz.build location.
@ -25,17 +26,17 @@ Proposal:
Initial Algorithm
Given a file, which includes the filename and the path from gecko root, we want to find the
correct moz.build file and location within that file.
correct moz.build file and location within that file.
Take the path of the file, and iterate up the directory tree, looking for moz.build files as
we go.
Consider each of these moz.build files, starting with the one closest to the file.
Within a moz.build file, identify the SOURCES or UNIFIED_SOURCES block(s) that contains a file
in the same directory path as the file to be added.
in the same directory path as the file to be added.
If there is only one such block, use that one.
If there are multiple blocks, look at the files within each block and note the longest length
of a common prefix (including partial filenames - if we just did full directories the
result would be the same as the prior step and we would not narrow the results down). Use
the block containing the longest prefix. (We call this 'guessing'.)
of a common prefix (including partial filenames - if we just did full directories the
result would be the same as the prior step and we would not narrow the results down). Use
the block containing the longest prefix. (We call this 'guessing'.)
Result of the proposal:
The initial implementation works on 1675 of 1977 elligible files.
@ -46,8 +47,8 @@ Result of the proposal:
- per-cpu-feature files, where only a single file is added under a conditional
- When guessing, because of a len(...) > longest_so_far comparison, we would prefer the
first block we found.
- Changing this to prefer UNIFIED_SOURCES in the event of a tie
yielded 17 additional correct assignments (about a 1% improvement)
- Changing this to prefer UNIFIED_SOURCES in the event of a tie
yielded 17 additional correct assignments (about a 1% improvement)
- As a result of the change immediately above, when guessing, because given equal
prefixes, we would prefer a UNIFIED_SOURCES block over other blocks, even if the other
blocks are longer
@ -59,6 +60,7 @@ Result of the proposal:
- Those specified in source assignments composed of generators (e.g. [f for f in '%.c'])
- Those specified in source assignments to subscripted variables
(e.g. SOURCES += foo['x86_files'])
We needed to iterate up the directory and look at a different moz.build file _zero_ times.
This indicates this code is probably not needed, and therefore we will remove it from the
algorithm.
@ -87,7 +89,7 @@ source-assignment
We specifically look only for these two variable names to avoid identifying things
such as CXX_FLAGS.
Sometimes; however, there is an intermediary variable, such as SOURCES += celt_filenames
Sometimes; however, there is an intermediary variable, such as `SOURCES += celt_filenames`
In this situation we find the celt_filenames assignment, and treat it as a 'source-assignment'
source-assignment-location
@ -106,12 +108,12 @@ source-assignment-location
For example:
When SOURCES += ['ffpvx.xpp'] appears as the first line of the file (or any other
unindented-location) its source-assignment-location will be "> SOURCES 1".
When `SOURCES += ['ffpvx.xpp']` appears as the first line of the file (or any other
unindented-location) its source-assignment-location will be `> SOURCES 1`.
When SOURCES += ['ffpvx.xpp'] appears inside a conditional such as
When `SOURCES += ['ffpvx.xpp']` appears inside a conditional such as
`CONFIG['OS_TARGET'] == 'WINNT'` then its source-assignment-location will be
"> if CONFIG['OS_TARGET'] == 'WINNT' > SOURCES 1"
`> if CONFIG['OS_TARGET'] == 'WINNT' > SOURCES 1`
When SOURCES += ['ffpvx.xpp'] appears as the second line of the file, and a different
SOURCES += [] was the first line, then its source-assignment-location will be "> SOURCES 2".
@ -146,9 +148,9 @@ normalized-filename
Normalization gets more complicated when dealing with separate vendoring and moz.yaml
directories. This is because a file can be considered normalized when it looks like
third_party/libdav1d/src/a.cpp
third_party/libdav1d/src/a.cpp
_or_ when it looks like
media/libdav1d/../../third_party/libdav1d/src/a.cpp
media/libdav1d/../../third_party/libdav1d/src/a.cpp
This is because in the moz.build file, it will be specified as
`../../third_party/libdav1d/src/a.cpp` and we 'normalize' it by prepending the path to the
moz.build file.
@ -162,13 +164,13 @@ normalized-filename
Whenever a filename is normalized, it should be specified as such in the variable name,
either as a prefix (normalized_filename) or a suffix (target_filename_normalized)
statistic_
statistic
Using some hacky stuff, we report statistics about how many times we hit certain branches of
the code.
e.g.
"How many times did we refine a guess based on prefix length"
"How many times did we refine a guess based on the number of files in the block"
"What is the histogram of guess candidates"
- "How many times did we refine a guess based on prefix length"
- "How many times did we refine a guess based on the number of files in the block"
- "What is the histogram of guess candidates"
We do this to identify how frequently certain code paths were taken, allowing us to identify
strange behavior and investigate outliers. This process lead to identifying bugs and small
@ -524,11 +526,13 @@ def get_mozbuild_file_search_order(
Returns an ordered list of normalized moz.build filenames to consider for a given filename
normalized_filename: a source filename normalized to the gecko root
moz_yaml_dir: the path from gecko_root to the moz.yaml file (which is the root of the
moz.build files)
moz_yaml_dir: the path to where the library's source files are
all_mozbuild_filenames_normalized: (optional) the list of all third-party moz.build files
moz_yaml_dir: the path from gecko_root to the moz.yaml file (which is the root of the
moz.build files)
moz_yaml_dir: the path to where the library's source files are
all_mozbuild_filenames_normalized: (optional) the list of all third-party moz.build files
If all_mozbuild_filenames_normalized is not specified, we look in the filesystem.
The list is built out of two distinct steps.
@ -541,6 +545,9 @@ def get_mozbuild_file_search_order(
directory.
Example:
.. code-block:: python
When moz_yaml directory != vendoring_directory:
moz_yaml_dir = foo/bar/
vendoring_dir = third_party/baz/
@ -680,7 +687,7 @@ def guess_best_assignment(source_assignments, filename_normalized):
assignment which contains a filename with the longest matching prefix.
e.g: "foo/asm_neon.c" compared to ["foo/main.c", "foo/all_utility.c"], ["foo/asm_arm.c"]
-> ["foo/asm_arm.c"] (match of foo/asm_)
-> ["foo/asm_arm.c"] (match of `foo/asm_`)
"""
length_of_longest_match = 0
source_assignment_location_of_longest_match = None
@ -722,9 +729,9 @@ def edit_moz_build_file_to_add_file(
I had _really_ hoped to replace this whole damn thing with something that adds a
node to the AST, dumps the AST out, and then runs black on the file but there are
some issues:
- third party moz.build files (or maybe all moz.build files) aren't always run
through black
- dumping the ast out losing comments
- third party moz.build files (or maybe all moz.build files) aren't always run through black
- dumping the ast out losing comments
"""
# Make sure that we only write in forward slashes

25
python/mozbuild/mozpack/errors.py
View File

@ -21,41 +21,54 @@ class ErrorCollector(object):
Warnings, errors and fatal errors may be logged by calls to the following
functions:
errors.warn(message)
errors.error(message)
errors.fatal(message)
- errors.warn(message)
- errors.error(message)
- errors.fatal(message)
Warnings only send the message on the logging output, while errors and
fatal errors send the message and throw an ErrorMessage exception. The
exception, however, may be deferred. See further below.
Errors may be ignored by calling:
errors.ignore_errors()
- errors.ignore_errors()
After calling that function, only fatal errors throw an exception.
The warnings, errors or fatal errors messages may be augmented with context
information when a context is provided. Context is defined by a pair
(filename, linenumber), and may be set with errors.context() used as a
context manager:
.. code-block:: python
with errors.context(filename, linenumber):
errors.warn(message)
Arbitrary nesting is supported, both for errors.context calls:
.. code-block:: python
with errors.context(filename1, linenumber1):
errors.warn(message)
with errors.context(filename2, linenumber2):
errors.warn(message)
as well as for function calls:
.. code-block:: python
def func():
errors.warn(message)
with errors.context(filename, linenumber):
func()
with errors.context(filename, linenumber):
func()
Errors and fatal errors can have their exception thrown at a later time,
allowing for several different errors to be reported at once before
throwing. This is achieved with errors.accumulate() as a context manager:
.. code-block:: python
with errors.accumulate():
if test1:
errors.error(message1)

5
python/mozbuild/mozpack/executables.py
View File

@ -66,9 +66,8 @@ def is_executable(path):
"""
Return whether a given file path points to an executable or a library,
where an executable or library is identified by:
- the file extension on OS/2 and WINNT
- the file signature on OS/X and ELF systems (GNU/Linux, Android, BSD,
Solaris)
- the file extension on OS/2 and WINNT
- the file signature on OS/X and ELF systems (GNU/Linux, Android, BSD, Solaris)
As this function is intended for use to choose between the ExecutableFile
and File classes in FileFinder, and choosing ExecutableFile only matters

13
python/mozbuild/mozpack/files.py
View File

@ -68,12 +68,9 @@ def _open(path, mode="r"):
class Dest(object):
"""
Helper interface for BaseFile.copy. The interface works as follows:
- read() and write() can be used to sequentially read/write from the
underlying file.
- a call to read() after a write() will re-open the underlying file and
read from it.
- a call to write() after a read() will re-open the underlying file,
emptying it, and write to it.
- read() and write() can be used to sequentially read/write from the underlying file.
- a call to read() after a write() will re-open the underlying file and read from it.
- a call to write() after a read() will re-open the underlying file, emptying it, and write to it.
"""
def __init__(self, path):
@ -1115,8 +1112,8 @@ class ComposedFinder(BaseFinder):
"""
Composes multiple File Finders in some sort of virtual file system.
A ComposedFinder is initialized from a dictionary associating paths to
*Finder instances.
A ComposedFinder is initialized from a dictionary associating paths
to `*Finder instances.`
Note this could be optimized to be smarter than getting all the files
in advance.

10
python/mozbuild/mozpack/mozjar.py
View File

@ -39,19 +39,24 @@ class JarStruct(object):
field names. In the latter case, the field is considered to be a string
buffer with a length given in that field.
For example,
.. code-block:: python
STRUCT = [
('version', 'uint32'),
('filename_size', 'uint16'),
('filename', 'filename_size')
]
describes a structure with a 'version' 32-bits unsigned integer field,
followed by a 'filename_size' 16-bits unsigned integer field, followed by a
filename_size-long string buffer 'filename'.
Fields that are used as other fields size are not stored in objects. In the
above example, an instance of such subclass would only have two attributes:
obj['version']
obj['filename']
- obj['version']
- obj['filename']
filename_size would be obtained with len(obj['filename']).
JarStruct subclasses instances can be either initialized from existing data
@ -561,6 +566,7 @@ class JarWriter(object):
- (...)
- End of central directory, pointing at first central directory
entry.
The duplication of the End of central directory is to accomodate some
Zip reading tools that want an end of central directory structure to
follow the central directory entries.

2
python/mozbuild/mozpack/unify.py
View File

@ -208,7 +208,7 @@ class UnifiedFinder(BaseFinder):
class UnifiedBuildFinder(UnifiedFinder):
"""
Specialized UnifiedFinder for Mozilla applications packaging. It allows
"*.manifest" files to differ in their order, and unifies "buildconfig.html"
``*.manifest`` files to differ in their order, and unifies ``buildconfig.html``
files by merging their content.
"""

5
python/mozlint/mozlint/result.py
View File

@ -123,11 +123,14 @@ class Issue(object):
class IssueEncoder(JSONEncoder):
"""Class for encoding :class:`~result.Issue`s to json.
"""Class for encoding :class:`~result.Issue` to json.
Usage:
.. code-block:: python
json.dumps(results, cls=IssueEncoder)
"""
def default(self, o):

2
python/mozlint/mozlint/util/implementation.py
View File

@ -21,7 +21,7 @@ class LintProcess(ProcessHandlerMixin, ABC):
def process_line(self, line):
"""Process a single line of output.
The implementation is responsible for creating one or more :class:`~mozlint.result.Issue`s
The implementation is responsible for creating one or more :class:`~mozlint.result.Issue`
and storing them somewhere accessible.
Args:

2
taskcluster/gecko_taskgraph/actions/registry.py
View File

@ -116,7 +116,7 @@ def register_callback_action(
JSON schema specifying input accepted by the action.
This is optional and can be left ``null`` if no input is taken.
permission : string
This defaults to ``generic` and needs to be set for actions that need
This defaults to ``generic`` and needs to be set for actions that need
additional permissions. It appears appears in ci-configuration and
various role and hook
names.

2
taskcluster/gecko_taskgraph/loader/multi_dep.py
View File

@ -79,7 +79,7 @@ def loader(kind, path, config, params, loaded_tasks):
def skip_only_or_not(config, task):
"""Return True if we should skip this task based on only_ or not_ config."""
"""Return True if we should skip this task based on `only_` or `not_` config."""
only_platforms = config.get("only-for-build-platforms")
not_platforms = config.get("not-for-build-platforms")
only_attributes = config.get("only-for-attributes")

2
taskcluster/gecko_taskgraph/transforms/task.py
View File

@ -2082,7 +2082,7 @@ def chain_of_trust(config, tasks):
@transforms.add
def check_task_identifiers(config, tasks):
"""Ensures that all tasks have well defined identifiers:
^[a-zA-Z0-9_-]{1,38}$
``^[a-zA-Z0-9_-]{1,38}$``
"""
e = re.compile("^[a-zA-Z0-9_-]{1,38}$")
for task in tasks:

2
taskcluster/gecko_taskgraph/transforms/test/other.py
View File

@ -775,7 +775,7 @@ def set_test_setting(config, tasks):
This transform adds a ``test-setting`` object to the ``extra`` portion of
all test tasks, of the form:
.. code-block:: json
.. code-block::
{
"platform": { ... },

8
testing/mozbase/manifestparser/manifestparser/filters.py
View File

@ -439,9 +439,11 @@ class tags(InstanceFilter):
class failures(InstanceFilter):
"""
[test_foobar.html]
fail-if =
keyword # <comment>
.. code-block:: ini
[test_foobar.html]
fail-if =
keyword # <comment>
:param keywords: A keyword to filter tests on
"""

16
testing/mozbase/mozdebug/mozdebug/mozdebug.py
View File

@ -132,15 +132,15 @@ def get_debugger_info(debugger, debuggerArgs=None, debuggerInteractive=False):
"""
Get the information about the requested debugger.
Returns a dictionary containing the |path| of the debugger executable,
if it will run in |interactive| mode, its arguments and whether it needs
to escape arguments it passes to the debugged program (|requiresEscapedArgs|).
If the debugger cannot be found in the system, returns |None|.
Returns a dictionary containing the ``path`` of the debugger executable,
if it will run in ``interactive`` mode, its arguments and whether it needs
to escape arguments it passes to the debugged program (``requiresEscapedArgs``).
If the debugger cannot be found in the system, returns ``None``.
:param debugger: The name of the debugger.
:param debuggerArgs: If specified, it's the arguments to pass to the debugger,
as a string. Any debugger-specific separator arguments are appended after these
arguments.
as a string. Any debugger-specific separator arguments are appended after
these arguments.
:param debuggerInteractive: If specified, forces the debugger to be interactive.
"""
@ -217,8 +217,8 @@ def get_default_debugger_name(search=DebuggerSearch.OnlyFirst):
Get the debugger name for the default debugger on current platform.
:param search: If specified, stops looking for the debugger if the
default one is not found (|DebuggerSearch.OnlyFirst|) or keeps
looking for other compatible debuggers (|DebuggerSearch.KeepLooking|).
default one is not found (``DebuggerSearch.OnlyFirst``) or keeps
looking for other compatible debuggers (``DebuggerSearch.KeepLooking``).
"""
mozinfo.find_and_update_from_json()

2
testing/mozbase/mozinfo/mozinfo/mozinfo.py
View File

@ -280,7 +280,7 @@ def find_and_update_from_json(*dirs, **kwargs):
:param tuple dirs: Directories in which to look for the file.
:param dict kwargs: optional values:
raise_exception: if True, exceptions are raised.
False by default.
False by default.
:returns: None: default behavior if mozinfo.json cannot be found.
json_path: string representation of mozinfo.json path.
:raises: IOError: if raise_exception is True and file is not found.