Messages in this thread | | | Date | Sun, 27 Mar 2022 12:27:20 +0700 | Subject | Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title | From | Bagas Sanjaya <> |
| |
On 26/03/22 20.56, Mauro Carvalho Chehab wrote: > Hmm... I can't really see any differences... What this patch seems to be > doing is to just change the markups for each level. > > See, on Sphinx, the first markup (whatever it is) is level 1, level 2 > the second different markup and so on. > > So, before this patch, kernel-doc.rst had: > > level 1: Writing kernel-doc comments > ===================================== > > level 2: How to format kernel-doc comments > ------------------------------------------ > > level 3: Function parameters > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > And after it, it will have: > > ==================================== > level 1: Writing kernel-doc comments > ==================================== > > level 2: How to format kernel-doc comments > ========================================== > > level 3: Function parameters > ---------------------------- > > No semantic changes at all. > > The only (eventual) value of a change like that would be to make the > levels more uniform, but IMO, it is not worth to apply a change like > that, as: > > 1. There are a lot other documents that don't use the more commonly > used level standard; > > 2. Making all .rst files to use the same definitions is hard; > > 3. Even if we place everything using identical markups for every > level, as new stuff gets added, different (still valid) > markups could be used on newer documents. > > Regards, > Mauro >
Indeed, fixing heading levels when adding title heading is required because without it, Sphinx will complain "indentation inconsistency" error.
Maybe better splitting indentation level changes into its own patch, right?
-- An old man doll... just what I always wanted! - Clara
| |