I don't think I thought about overloads.

We do not use \libmember broadly right now, because we sometimes have // comments later in the same line, aligned with nearby comments. And the necessary LaTeX escape-foo plus the \libmember macro invocation makes the alignment non-obvious in the source code, which doesn't help the editing.

So, please hold back on global \libmember patches.

Ah I see, makes sense.

An alternative idea I had was that perhaps there could be an environment that wraps a whole declaration, so that instead of

struct X {
  int @\libmember{f}{X}@();
};

you get something more along the lines of

struct X {
  @\begin{libmember}{f}{X}@
  int f();
  @\end{libmember}@
};

Bit more verbose, but easy to edit, and even better for cxxdraft-htmlgen because then I can make it highlight the whole declaration instead of just the name.

I have no idea if mixing environments with @ like this is even possible in LaTeX though.

Add-on: I think we're looking forward to \libmember patches where the library member is defined in the class or header synopsis and does not have a separate \itemdecl. (The status quo here is that we either have no index entry, or an index entry that points to the start of the synopsis. Neither option is good.)

struct X {
  @\begin{libmember}{f}{X}@
  int f();
  @\end{libmember}@
};

There's a problem with this: the codeblock environment respects whitespace, so the above will render as

struct X {
  
  int f();
  
};

(with blank lines before and after f). This means we need really ugly markup for a lot of the cases where we try to put index entries inside codeblocks. :-(

IIRC this kind of formatting works OK:

struct X {
  // comment for the below typedef@%
  \libindex{...}%
  \libindex{...}@
  using foobar_t = int;
}

... but you need to be careful about which linebreaks you do and do not comment out, and not all declarations are preceded by a comment that can be so annotated.

As a general goal, every library declaration should have an index entry. If it has an \itemdecl, we want an index entry pointing to that. If it has a synopsis entry, we want an index entry pointing to that (ideally to the right place in the synopsis, using either the above technique or using \libmember, depending on the situation, but a lot of pre-existing entries point to the start of the synopsis, and that might be OK in limited cases if the synopsis is very short, but is usually undesirable). I don't think we have any current intention to index both places for entities with an \itemdecl, though we could reconsider that if people think it's useful.

Somewhat on the topic: There's a few instances where \libraryglobalindex is not being parsed correctly, and showing up naked in the text, for example http://eel.is/c++draft/new.syn. Not sure if it's an eel.is issue or what have you, just wanted to point that out :)

That's Eelis/cxxdraft-htmlgen#71, so I guess it's an eel.is's issue.