-// for refstyle, given pfx:suffix, we want to return "\\pfxcmd"
-// and put "suffix" into label.
-// otherwise, we put the reference into label.
-docstring InsetRef::getFormattedCmd(
- docstring const & ref, docstring & label) const
+// the ref argument is the label name we are referencing.
+// we expect ref to be in the form: pfx:suffix.
+//
+// if it isn't, then we can't produce a formatted reference,
+// so we return "\ref" and put ref into label.
+//
+// for refstyle, we return "\pfxcmd", and put suffix into
+// label and pfx into prefix. this is because refstyle expects
+// the command: \pfxcmd{suffix}.
+//
+// for prettyref, we return "\prettyref" and put ref into label
+// and pfx into prefix. this is because prettyref uses the whole
+// label, thus: \prettyref{pfx:suffix}.
+//
+docstring InsetRef::getFormattedCmd(docstring const & ref,
+ docstring & label, docstring & prefix) const