1

When writing the doxygen comment for a function, I use @param for its parameters, and I can also use @tparam for its template parameters. However, when writing a GPU kernel (OpenCL or CUDA), I can't quite find a way to document the choices w.r.t. the grid/nd-range:

  • Dimensionality - how many dimensions?
  • What do the "axes" of the grid signify? Which dimension corresponds to what parameter?
  • What are block (OpenCL workgroup) sizes, number of blocks, and/or overall size in each dimenion?

I'm looking for an appropriate doxygen feature with which to record this information in the comment - preferably better than a @note...

einpoklum
  • 118,144
  • 57
  • 340
  • 684
  • Also give an example of what you have /want to accomplish. Which doxygen version? – albert May 04 '20 at 15:30
  • @albert: Whatever doxygen version is on the system on which the source code is being read. If there's some facility for this only in recent doxygen versions, do let me know. – einpoklum May 04 '20 at 15:33
  • 2
    I don't know which doxygen version is is on the system, maybe `doxygen -v` shines a light on it. The second remark I don't understand. And please create a MWE that shows your problem. – albert May 04 '20 at 15:50
  • Maybe a doxygen @page ? – Marc Alff May 06 '20 at 16:39
  • @MarcAlff: Can you expand on that? – einpoklum May 06 '20 at 21:50
  • Doxygen can be used to document low level code items (functions, parameters, ...), which is what people use in general. Less known, doxygen can also have documentation written as page / section / subsection, much like a structured document. This is most useful to document something that is not specific to a given function, but global to some software, like your GPU kernel. See examples of pages in the MySQL doc (that I wrote) : https://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_PFS.html#PFS_MAIN_INTRO See "main pages" and "related pages" in the overall doc. – Marc Alff May 07 '20 at 00:30
  • @MarcAlff: Ok, I see, but - I do want to document a single (kernel) function here. – einpoklum May 07 '20 at 08:37

1 Answers1

2

Doxygen has no idea what a compute kernel is as a concept. So it has no special documentation features for features of compute kernels, like workgroup size and the like. So you're going to have to improvise.

You could use the main function for the kernel and put the information there, or you could put it in the @file documentation for the file.

Nicol Bolas
  • 449,505
  • 63
  • 781
  • 982