Add various specifiers to functions and variables

[jakobandersen]

Convert various specifiers on functions and variables.

Fixes (part 1 of) #600.

[jakobandersen]

Example to check the rendering:

struct A {
	static void fStatic();
	inline void fInline();
	friend void fFriend();
	virtual void fPureVirtual() = 0;
	virtual void fVirtual();
	explicit A();
	constexpr void fConstexpr();
public:
	static int vStatic;
	mutable int vMutable;
};

// doc
extern void fExtern();
// doc
thread_local int vThreadLocal;

.. doxygenstruct:: A
	:members:
	:undoc-members:

.. doxygenfunction:: fExtern
.. doxygenvariable:: vThreadLocal

[jakobandersen]

(The linting errors seems to be unrelated to the PR but due to a new mypy version.)

[vermeeren]

This is great, thanks @jakobandersen !

[ninkibah]

Is there a way to not output an inline specifier? My code is highly templated C++, where the functions are all implemented inline, although without the explicit specifier. All of these function templates are marked as inline in the documentation and it's ugly and I would prefer they were not shown.

I presume Doxygen is passing on these specifier to breathe. If there's a workaround using doxygen, I'd be happy to try that.

[jakobandersen]

I don't think Breathe has options to do that, and I don't know about Doxygen. Theoretically, if there are all templates, the inline specifier is redundant as far as I remember. Though, I guess the compilers may still use it as a slight hint for function inlining.

[ninkibah]

Sorry if I wasn't explicit enough. I write code like:

template<typename T>
void foo(T&) {}

This function will end up being marked as inline in the HTML documentation generated by Sphinx. That's what I was hoping to avoid.

[ninkibah]

I've raised an issue on the doxygen project, where, I believe, the problem lies:
doxygen/doxygen#8458

I think this issue can be closed.

For anybody who is looking for a quick workaround, I was able to add a little jquery script in custom.js to hide the inline specifier from the HTML.

In conf.py:

html_js_files = [
    'custom.js'
]

In _static/custom.js, I added the following:

$(document).ready(function() {
  $("em.property > span.pre:contains('inline')").hide();
});

This works for the readthedocs theme. Other themes may use different selectors. That's beyond my sphinx knowledge.

[jakobandersen]

I'm not exactly sure what the rationale for why Doxygen marks it inline when it's a member function and not when it's an ordinary function, but in any case: your hax will definitely remove them.
Just as a heads up: this will break if/when sphinx-doc/sphinx#9023 gets merged. Though something like .sig.cpp .k > span.pre:contains('inline') is the most specific selector I can think will work then.

[ninkibah]

Jakob, thanks very much for the advice. The spacing in declarations is not always great, so I hope that the above issue makes it easier to make the spacing look nice. I should probably talk to the readthedocs theme people about this.

[jakobandersen]

Oh, right, I just tried locally and I don't see any spacing and wrapping issues with that PR + sphinx_rtd_theme!