Doc string object in C ++

Languages ​​such as Python, MATLAB, E-Lisp have a great tool for doc strings. Thanks to this function, using just a few keystrokes in the terminal, you can get documentation about the functions / module that you wrote and imported into your code.

Now there is some kind of “technique” (library, editor tricks, whatever) to get a similar object in C ++ / C. Suppose that I include the documentation of the function in the source file in the function head, then I would like to type a command, for example getinfo, on the terminal. (something like a man page)

I know that such a “person” tool exists for many C functions, but the documentation for these functions is written to separate text files from the source code. I would like documentation in place

+6
source share
3 answers

You can use something like Doxygen . It supports the creation of man pages among other formats.

+5
source

Visual Studio can / will generate pop-ups containing information extracted from DocXml comments. You must compile with /doc , which will extract the XML from the comments into a .xdc file. Then you must run xdcmake to compile the .xdc files into an XML file. You usually handle all this automatically during the build process, so you don’t have to do much manually (except for the comments themselves, of course). The only thing to keep in mind is that the code (at least the declaration) must be created before you get the pop-ups.

I feel obligated to add that IMO, most of these comments are usually very close to useless. If the corporate standard makes them inevitable, so be it, but if they honestly provide some useful information, I would think that this indicates a problem (“Code smell” if you prefer this wording). In most cases, a combination of the function name (or any other) and parameter names / types should make the use of the function understandable.

+1
source

If you mark your code with comments in syntax like Javadoc, you can create documentation for your code in various formats using Doxygen . It can generate, among other things, man pages, but it seems that the preferred user format used by users is HTML pages.

0
source

Source: https://habr.com/ru/post/916854/


All Articles