1783787 - Make markers APIs easier to use, friendlier with IDE contextual help

Status: NEW

(Core :: Gecko Profiler, task, P3)

Description

[Gerald Squelart (he/him) (not at Mozilla since 2022-09-15)]

The profiler_add_marker is fairly complex, and forces most developers to read the docs when using it.

To help with that, it may be possible to subtly change the API to offer contextual help while typing the call in IDEs.

---

Spawned from a discussion between :mstange and :gerald, with some ideas:

[m] I find profiler_add_marker so hard to use
[g] Ideas on how it could be made easier to use?
[g] The difficulty comes from its flexibility: Set of options specified through MarkerOptions and its variadic contructor, variadic template arguments dependent on the chosen marker type.
[g] For the options, we could do something IDE-friendlier with a chain of builders, something like: profiler_add_marker("name", OTHER, MarkerOptions{}. [after pressing the dot, the IDE should list the available functions, which could be: ] CaptureStack(). [and continuing to build: ] StartIntervalNow(), ...). (But I'd have to see if the generated code is still optimized.)
[m] also, having some examples in the code comments for profiler_add_marker would help
[m] the implicit conversions are making it hard, too
[m] the first argument takes a ProfilerString8View
[m] but apparently I can pass a const char[n]?
[m] there are some places that pass a ProfilerStringView without the 8
[m] and then for the categories, can I pass a geckoprofiler::category::MY_CATEGORY directly or do I need to wrap it in a MarkerCategory?
[m] how is a MarkerCategory different from a normal category, why does it need its own type?
[g] C++ type safety, consistency with other Marker... parameter types, and it forces to specify the full category pair in the profiler_add_marker call even though we currently only forward the super-category to the front-end.
[g] But yeah, maybe we could just directly use ProfilingCategoryPair 🤔 (it's an enum class, so typing ProfilingCategoryPair:: should show the list of values in IDEs).