Re: [PATCH 1/4] doc: Migrate CodingStyle wiki page to sphinx

[Tom Rini <trini@konsulko.com>]

[-- Attachment #1: Type: text/plain, Size: 2563 bytes --]

On Sat, Jul 09, 2022 at 08:12:27AM +0200, Heinrich Schuchardt wrote:
> On 6/27/22 19:17, Tom Rini wrote:
> > Move the current CodingStyle wiki page to doc/develop/codingstyle.rst.
> > The changes here are for formatting or slight rewording so that it reads
> > well when linking to other sphinx documents.
[snip]
> > +U-Boot adopted the kernel-doc annotation style, this is the only exception from
> > +multi-line comment rule of Coding Style. While not mandatory, adding
> > +documentation is strongly advised. The Linux kernel `kernel-doc <https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html>`_ documentation applies with no changes.
> 
> Developers tend to read the rst files with text editors. Please, keep
> lines short (80 characters). `kernel-doc can go onto the next line.

Linux doesn't have a hard 80 character limit anymore and neither do we,
keep in mind.

> > +applies with no changes.
> > +
> > +Use structures for I/O access
> > +-----------------------------
> > +
> > +U-Boot typically uses a C structure to map out the registers in an I/O region, rather than offsets. The reasons for this are:
> > +
> > +* It dissociates the register location (offset) from the register type, which
> > +  means the developer has to make sure the type is right for each access,
> > +  whereas with the struct method, this is checked by the compiler;
> 
> Please, add blank lines between bullets.

Different than markdown, OK.

[snip]
> > +Tests
> > +-----
> > +
> > +
> > +Please add tests when you add code. Please change or expand tests when you change code.
> > +
> > +Run the tests with::
> > +
> 
> %s/::/:/
> 
> .. code-block:: bash
> 
> > +   make check
> > +   make qcheck   (skips some tests)
> > +
> > +Python tests are in test/py/tests - see the docs in test/py for info.
> 
> Please, add a reference to doc/develop/tests_writing.rst
> 
> > +
> > +Try to write your tests in C if you can. For example, tests to check a command
> > +will be much faster (10-100x or more) if they can directly call run_command()
> 
> %s/10-100x/10 - 100x/
> Please, avoid duplicating information from tests_writing.rst.
> 
> > +and ut_check_console_line() instead of using Python to send commands over a
> > +pipe to U-Boot.
> > +
> > +Tests run all supported CI systems (gitlab, travis, azure) using scripts in the
> 
> %s/gitlab/Gitlab/
> %s/azure/Azure/
> 
> We don't use Travis CI anymore.

This is more substantive than wiki->rST so I'll handle this in another
patch.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]