How to document a expl3 macro using dtx

While you can start form ltxdoc and 'roll your own', the recommended approach is to use l3doc, which is the class used the the LaTeX3 team for expl3 itself. This is currently a rather large collection of hacks, but does deal correctly with things like _ in names, and also provides a richer set of documentation environments than ltxdoc. Regrettably, l3doc is lacking really comprehensive documentation: as I say, it's not exactly perfect internally! You can typeset l3doc.dtx to at least get some information, however.

Perhaps the best way to get the hang of things is to take a look at some of the LaTeX3 sources. I'd recommend avoiding l3doc.dtx itself and probably l3bootstrap.dtx, l3names,dtx and l3basics.dtx as they are atypical: something like l3clist.dtx is probably a rather better place to look. (As well as the use of l3doc, the sources show the 'house style' the team have standardised on. We are keen to encourage that as a more general 'LaTeX3 code style': while you might not totally agree with every decision, in the long term it would be good if most LaTeX3 code looks the same irrespective of author, as this will aid with maintenance.)

What I do is use skdoc (which I've written, although since it's based on ydoc presumably this'll work with at least ydoc as well assuming you load expl3), and issue the following before the implementation part of the documentation:

\ExplSyntaxOn
\cs_set_protected_nopar:Npn\ExplHack{
    \char_set_catcode_letter:n{ 58 }
    \char_set_catcode_letter:n{ 95 }
}
\ExplSyntaxOff
\ExplHack

This makes the macro environments (as well as \cs and friends) read underscores and colons as “letters” (i.e. part of the macro name) as appropriate in LaTeX3 code.