Could anyone please suggest a proper format of comments I should use in a C++ project? I think that there is some analog of javadoc format, but I can't find which one. Is there any de-facto standard of that kind? Thanks!
Doxygen is used rather frequently for C++ projects (Doxygen supports other languages as well). You can use Doxygen-style comments as a starting point (here are some examples). Just be consistent.
It's quite controversial as a subject in every language.
While I appreciate the Doxygen answers, since it's effectively kind of a de facto standard, Doxygen itself supports multiple formats.
C++ supports 2 styles of comments:
/**/ multi-line comment
// until the end of line comment
I would advise not to use the former style. The issue is that it does not nest, which is quite annoying when for testing purpose you wish to comment out a whole block of code.
My 2 cents, as the saying goes.
Your mention of javadoc suggests you might be thinking of doxygen. This is a kit which supports structured comments in C++ and other languages, and can produce output in HTML and (if I recall correctly) PDF. It supports a variety of comment styles, including one which looks very much like javadoc.
It works well, and is broadly used.
Related
NB: This question is more about how to navigate through/decipher OCaml source code, than about the specifics of the items listed below.1
I've come across the expressions
`Malformed
`Uchar
in some OCaml source code, but I can't find definitions for them.
Are they somehow built-in, i.e. part of the standard language?
If not, where does one go when one wants to find out such definitions? (Actually, it's not clear to me whether the leading backtick is part of the name or is a separate operator.)
1I'm having a horrible time making sense of OCaml source code. Usually I have no problem picking up new programming languages, but with OCaml I can't find anything where I expect to find it, and when I do find something it comes along with 100x more undefined/differently-defined/outright bizarre names/concepts, so it's a losing battle.
It's a polymorphic variant, you can read about it in the OCaml manual here
For other basic language features you would not understand, well, you should first read the whole part 1 of the manual
Here is how the manual is organized:
Quick introduction through the language
The whole language (two parts: first the legacy language, then the features added through time)
The standards shell tools manpages (compilers, interprets, ocamlbuild etc.)
The standard libraries
I noted from your previous questions that you use non-standard tools, such as opam and several libraries, make sure to check their documentations and note that some can extend your syntax.
I have to admit that the doc generally assumes people reading it already know about the concepts presented but you don't need to use them at first to master the language.
Happy hacking !
It is a polymorhic variant, that do bot need to be defined before usage. It is something between lisp's symbols and common ADT's. You think of it as a syntactically lighter version version of common ADTs.
I would suggest you to use utop as a playing ground to learn OCaml. Indeed, it is a damn easy language, it looks like to me that you have atacked it from a wrong side, or working with a program that is obfuscated.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
We all have the good habit of documenting our code, right?
Nowadays, in-code documentation itself has a syntax. It's almost like a programming language onto itself. The questions are:
What (How many) documentation syntax specifications exist?
Is there a standard documentation syntax?
Who is defining this standard? Is there an official committee or body (like there is one for defining C++ standards)?
Or has "doxygen" become the de-facto standard?
It's difficult not to have heard about doxygen. It is mentioned in every open source software project I have taken part in. Yet, looking at the official doxygen web site, it is far from obvious that doxygen is defining any kind of specification! The impression I get when I read "the ways it can help me", is that doxygen is simply a software to extract in-code documentation and present it in beautiful HTML pages. Looking at the doxygen front page, I could even think that doxygen could use any documentation syntax defined in 3rd party specifications and extract it and output it as HTML.
Also, it is interesting to note that the doxygen web site does not capitalize the word doxygen, as if it were not the brand of their software but a common noun (well, is it?)
What is doxygen really?
a parsing engine?
an HTML rendering engine?
a library that can be used by 3rd party software to render their own docs?
a documentation syntax (de facto) specification?
all of the above?
I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...
For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?
Also, looking at the Drupal project. They have:
their own API module which is "an implementation of a subset of the Doxygen documentation generator specification".
their own grammar parser module (to add to the list above, alongside doxygen itself, ANTLR, et all).
their own API web site running the two aforementioned modules, presenting the Drupal in-code "doxygen" documentation.
So, to take a C++ analogy, it seems that the word "doxygen" is overloaded and means different things in different contexts.
Within the Drupal project, "doxygen" does not refer to a software, but simply a (standard?) specification for documentation syntax even though, as I said above, the front page of the doxygen web site itself does not claim to be such a thing!
So, my parting question is:
Is there any other documentation syntax specification?
What (How many) documentation syntax specifications exist?
Almost every medium software development organization seems to have their own. Often they are included under the umbrella of "coding style guidelines".
Is there a standard documentation syntax?
There are a few standards that I am aware of which have some widespread use. This is surely not a comprehensive list:
JavaDoc
The C# XML documentation format (ECMA-334)
QDoc (sometimes confused as being the Doxygen)
RubyDoc
Plain Old Documentation (POD)
Who is defining this standard?
There is no standard.
Is there an official committee or body (like there is one for defining C++ standards)?
Not really, though the C# XML documentation format is managed by ECMA, which is a standards organization.
Or has "doxygen" become the de-facto standard?
Doxygen is not a standard. It recognizes a number of standards. See http://www.doxygen.nl/manual/features.html.
Typically most people use doxygen to generate docs they wrote while loosely following either the QDoc standard or the JavaDoc standard. Often when people talk of "the" doxygen standard, more often than not they mean the QDoc documentation style, plus some arbitrary usage of doxygen extensions. My experience is that most organization using doxygen aren't really following any particular convention very rigidly, simply because doxygen doesn't enforce one.
...it is far from obvious that doxygen is defining any kind of specification!
It isn't.
doxygen is simply a software to extract in-code documentation and present it in beautiful HTML pages.
Yes exactly. It also supports XML, Latex, RTF, and UNIX "man" page outputs.
Looking at the doxygen front page, I could even think that doxygen could use any documentation syntax defined in 3rd party specifications and extract it and output it as HTML.
Not any, but many.
Also, it is interesting to note that the doxygen web site does not capitalize the word doxygen, as if it were not the brand of their software but a common noun (well, is it?)
Its not a commercial product, Dimitri doesn't care much about branding.
What is doxygen really?
A documentation generation tool.
I am particularly confused as to the relationship between doxygen and other code parsers like ANTLR, boost-spirit, Ragel...
Those are parsing libraries.
For example, what is it that doxygen can do that ANTLR cannot, and that ANTLR can that doxygen cannot?
Libraries like ANTLR are used to build software, while doxygen is a specialized tool for generating documentation. So while you could use ANTLR to write a documentation generator, you wouldn't want to use doxygen to build a compiler (I don't say can't, because surely you could, I have seen stranger things).
Is there any other documentation syntax specification?
Already answered above.
Hope this helps.
there is no standard.
Doxygen style is almost standard (gcc template library uses it).
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
You are right - Doxygen is more of a documentation extraction application than a "commenting standard" per se. It supports many different documentation styles - JavaDoc (with '#' introducing a command), a Doxygen variant (with '\' introducing the same commands), Documentation XML, and many variations on the comment block format that is allowed. It is also able to use the formatting of comments to indicate what content is (e.g. brief descriptions need not be tagged as such, and can be taken from the first sentence or paragraph of the text, etc.)
As such, it is highly configurable but allows almost every programmer to have their own style which leads to a nonstandard mess from one project to another, and often between different comments within a single project - even when they are written by a single programmer! The plus side is that as long as the comment stays within the basic style, Doxygen will correctly extract the docs for you and format them all into a consistent external document. The minus side is that although many programmers "use doxygen comments" (which sounds standardised), their comment formats can often be totally dissimilar.
One solution (for Visual Studio) that can at least help with this disparity of styles within your own project/team/company is an addin I've written, AtomineerUtils. This helps you to author and update Doxygen, JavaDoc and XML documentation format comments - it auto-generates documentation to save lots of time, and updates comments to keep them in sync with changes to the code. During this process it can reformat the comment to achieve a very consistent and readable style (order the entries in a standard format, enforce blank lines between comments and code and between entries, word-wrap the text in entries, etc). The user can set up templates that control exactly how all of this works, so it's easy to achieve precisely the style you want, but make it consistent across all your projects. This improves consistency a lot when you have more than one programmer working on a body of code.
If you are documenting in Visual Studio, I would recommend the XML documentation format. It's not as human-readable as Doxygen/JavaDoc styles can be, but it's used by the IDE to provide live intellisense data on code as you type, and is exported to XML files that any application can easily process, which gives you a lot more flexibility. Doxygen can build docs from this format, so you can stil use the Doxygen tools with XML source comments too.
Is there any other documentation syntax specification?
Yes, of course. For example, there's JavaDoc (or however that's spelled). And Microsoft's XML stuff (however that's called).
However, it seems doxygen is pretty much the de-facto standard in the Open Source C++ arena, though. When I originally heard about doxygen (~10 years ago), there used to be others around, but it seems they've vanished.
We are slowly moving towards better-standardized commenting in a large C++ project, introducing Doxygen. I personally find it a pain typing in comments, especially since Java IDEs are so good at automating this.
So I wondered what tools there might be? A search turned up DoxyComment which looks quite nice, is this the best/standard tool or are there others worth a look too?
Atomineer is a tool that I and a few others have been using for documenting unmanaged C++ code with Doxygen markup. It's not free, but it is cheap, and may be worth a try:
http://www.atomineerutils.com/products.php
If typing the meta-comments which are instructions to doxygen is a significant part of your comment-writing effort, you're doing it wrong.
Comment should not include things which can be automatically determined by a tool, any programmer will determine just as much (or more) information from e.g. parameter names than any tool.
Another way to look at this is that doxygen already does an excellent job of presenting what can be automatically determined. You don't need to write: "B::B constructs a B object", since doxygen is going to sort it into the constructors section of the documentation automatically.
Focus on what's non-obvious, and take time to think about what you're writing.
Normally many functions and variables will have no need for an individual comment, since either the name is descriptive enough, or they are better explained in a class-level comment describing how multiple members interact.
Is there an equivalent to tidy for HTML code for C++? I have searched on the internet, but I find nothing but C++ wrappers for tidy, etc... I think the keyword tidy is what has me hung up.
I am basically looking for something to take code written by two people, and clean it up to a standardized style. Does such an app exist?
Thanks a bunch!
Artistic Style
is a source code indenter, formatter,
and beautifier for the C, C++, C# and
Java programming languages.
GC Great Code
is a well known C/C++ source code
beautifier.
Of course I find an answer to my own question moments later. What luck, I probably spent an hour searching earlier.
Should anyone be looking for the same thing, check out Uncrustify at http://uncrustify.sourceforge.net/
If you're using Visual Studio then you could take a look at StyleManager*. It's a VS add-in that makes it easy to set up formatting styles and apply them to code whenever you need to. It's a popular choice with VS users, and in particular was used by the DirectX SDK team to tidy up their sample code.
*Huge disclaimer: I'm one of the authors of this software, so apologies for the shameless plug!
You can tidy your code online, with this website:
https://codebeautify.org/cpp-formatter-beautifier
https://codebeautify.org/cpp-formatter-beautifier
A rather comprehensive site explaining the difficulties and solutions involved in using a dll written in c/c++ and the conversion of the .h header file to delphi/pascal was posted to a mailing list I was on recently, so I thought I'd share it, and invite others to post other useful resources for this, whether they be links, conversion tools, or book/paper titles.
One resource per answer please, so we'll end up with the most popular/best resources bubbling to the top.
Over at Rudy's Delphi Corner, he has an excellent article about the pitfalls of converting C/C++ to Delphi. In my opinion, this is essential information when attempting this task. Here is the description:
This article is meant for everyone who
needs to translate C/C++ headers to
Delphi. I want to share some of the
pitfalls you can encounter when
converting from C or C++. This article
is not a tutorial, just a discussion
of frequently encountered problem
cases. It is meant for the beginner as
well as for the more experienced
translator of C and C++.
He also wrote a "Conversion Helper Package" that installs into the Delphi IDE which aids in converting C/C++ code to Delphi:
(source: rvelthuis.de)
His other relevant articles on this topic include:
Using C++ Objects in Delphi
Using C object files in Delphi
Article at Rudy's Delphi Corner
Also, CodeGear hosts a rudimentary translation tool called CToPas (written by Ural Gunaydin).
I would like to highlight the Jedi Api Library, it is the Delphi translation of the Windows SDK headers. Might save you a lot of work if you need to translate headers from the SDK and is of course a good sample of conversions!
Since FreePascal is aimed at Delphi compatibiltiy among other things, i think H2Pas may be helpful too.
https://www.freepascal.org/tools/h2pas.var
HeadConv from DrBob is used quite a lot too, although I concur with Graza that manual translation is best.
use this option so the byte alignment is the same as C/C++ and then you don't need to add padding bytes in structs.
{$MINENUMSIZE 4}