Documentation writing style and format

1

Hello,

As a regular reader of OpenCV’s documentation pages, I think they are quite detailed and informative (at least for the parts I read regularly), yet they could probably use some improvements to make them easier to read and navigate. In particular, the formatting is not always consistent throughout a single page, especially regarding references to other functions, argument names or mathematical symbols.

I did not find any rule, advice or example on the Coding Style Guide wiki page, so I wanted to have your opinion about whether we should have at least some recommendations - like naming conventions for C++ code - and what they should be.

As a very short example I would suggest:

  • Use @ref or \ref doxygen tags when referring to other API functions to make them clickable links.
  • Use backticks (``) around parameter names, types or small expressions (like distCoeffs, vector<double> or src.size()) to make them stand out.
  • Use @f$ or \f$ doxygen tags around mathematical symbols / formulas so they are displayed nicely using Latex.

I know these “implicit conventions” are already used here and there but not systematically. Some other conventions may be used elsewhere, making the whole documentation quite heterogeneous in this regard. As a first step I am willing to make a proposal to add such a list to the wiki, and then start making some changes in the documentation to implement agreed-upon guidelines.

What do you think?

1 Like
2

I think you’ll have infinitely better reactions without the use of force, to put it mildly. force is highly unpopular for very good reasons.

whatever anyone writes, it won’t be found or read.

the best way to achieve your goal is making the existing documentation consistent yourself, not writing down how to do it.

people hate definitions. people are good at seeing patterns and replicating them, following examples.

3

Hi crackwitz,

Yes you’re right, that was an unfortunate poor choice of words/mistranslation! I meant “implement” rather than “enforce”. I’ll edit the original post to fix this.

Well… I don’t know about that. I did search the wiki for such guidelines but did not find any. There are guidelines about coding style though. But I guess you’re right saying that people tend to replicate existing patterns, and I’m definitely motivated to put some efforts into harmonizing as much as I can.

Anyway, besides writing official guidelines (that nobody will read :P), I thought it would be nice to hear from the community about those guidelines to make sure that people who care about this agree on them, hear about other proposals, etc.

2 Likes