Consulting Documentation

Another common task when developing is to consult documentation for a given function or method. Typically in this case you want to use a given method or function, and you know the class or library to which it belongs, but are unable to recall its exact signature or some other important detail. Hence you wish to quickly consult the documentation for the detail in question and get back to your code. The library in question may be internal (that is, project-specific), third-party (e.g. boost), or the standard library itself. The documentation may take the form of an online reference, a man or info page, or a commented declaration in source code.

Code Completion with Documentation

By far the most convenient form of documentation lookup is in the form of code completion. So as you type the name of the function or method in question, the mini buffer shows a summary including arguments, return types, etc.

See Coding Shortcuts for more details.

Online Documentation

Hence it is often the case that we wish to refer to a reference such as an online document, man page or similar. Unfortunately there does not seem to be a single good way to do this from within Emacs. It would be preferable to combine all third-party and standard libraries under one common, cross-linked, reference documentation system such as GNU Info. Unfortunately this does not seem feasible right now, as many libraries are just not documented in a compatible manner. Hence we need to go to several different sources for online documentation.

Manual pages are of course handy for many reasons, and these are accessible via M-x man. For some libraries, particularly GNU libraries, the Info documentation is superior, and that can be accessed via @<kbd>C-h i@</kbd>, a standard binding. I have found that to get the most out of Info, it is best to ensure that all of the standard Info locations are being provided to Emacs.

For the standard C++ library and some language features, I find it best to use online resources such as cppreference. As a well-trafficked wiki, this is generally up-to-date and accurate. Also it is generally superior to the default library documentation for either libstdc++ or libc++ (the GNU and Clang standard libraries, respectively).

For other libraries that are packaged by the operating system, it is often possible to install a documentation variant. This might, for example, place an HTML version of the library’s documentation on a shared local directory such as /usr/share/doc/blah. I find it convenient to configure a local web server to serve up this directory for browsing (e.g. http://localhost/boost to access the installed Boost doco).

C++ Symbol Lookup

As a further convenience, I have a few functions to look up the C++ type of the expression or declaration at the cursor, and dispatch a search request based on the namespace of that type. For example, let’s say I have the following file:

#include <vector>
void foo()
{
   std::vector<char> vec;
   vec.push_back('c');
}

I would like to be able to put my cursor on the vector<char> type declaration, or on the push_back method and invoke a function which would open reference documentation for either that type or that method.

By reference documentation, I mean some form of web-based resource which I can associate with the namespace of the type in question. So for example, I might want to refer to http://cppreference.com for any types in the “std” namespace.

So my initial attempt is here. This defines the semantic-browse-c++-doc function which you can bind to whatever key. I have mine bound to @<kbd>C-c Q@</kbd>, because it complements semantic-ia-get-doc which is bound to @<kbd>C-c q@</kbd>.

(defun my-cedet-c-hook ()
  ;; ...
  (local-set-key [(control c) (Q)] 'semantic-browse-c++-doc)
  (local-set-key [(control c) (q)] 'semantic-ia-show-doc)
  ;; ...
  )
(add-hook 'c-mode-common-hook 'my-cedet-c-hook)