Related
I'm quite confused by this paradox:
GCC ext apparently contains lots of broadly useful functionality. For example, ext/pb_ds/assoc_container.h lets you build an order statistic tree just by specifying particular template arguments, and ext/numeric contains the power(..) algorithm for O(lg N) exponentiation of a generic object to a non-zero integer power — this algorithm gets written from scratch all the time. There is also the rope data structure, algorithms for random sampling, and many others. Not things you would use every day, but definitely things that would be handy every other year or so.
Almost nobody seems to be using them. There is very little discussion on the web. There are some bug reports, and posts like this one suggesting either that these things are buggy and unmaintained or that there is no definitive guide on how to use them properly.
Now, trying to find the documentation, I type in gcc "ext" into Google, and get https://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/ as the first result. Going to Examples of Associate Containers gets me to another table of contents, but clicking on e.g. the link to basic_set.cc gives me a 404 page.
At this point I'm not even sure if this code had received enough testing to be able to rely on it for serious applications.
Is there any proper documentation for when and how to use #include <ext/numeric> and the like? Or at least examples and asymptotic complexity estimates?
Since it sounds like you've found a defect in the documentation, I'd suggest sending an e-mail to libstdc++#gcc.gnu.org to subscribe to the mailing list. I was able to find a mirror for the libstdc++ test suite on Github, which contains the examples you want. If you're looking for documentation for ext_numerics, it's at gcc.gnu.org/onlinedocs/libstdc++/manual/ext_numerics.html.
I am working on documenting a new and expanded Lua API for the game Bitfighter (http://bitfighter.org). Our Lua object model is a subset of the C++ object model, and the methods exposed to Lua that I need to document are a subset of the methods available in C++. I want to document only the items relevant to Lua, and ignore the rest.
For example, the object BfObject is the root of all the Lua objects, but is itself in the middle of the C++ object tree. BfObject has about 40 C++ methods, of which about 10 are relevant to Lua scripters. I wish to have our documentation show BfObject as the root object, and show only those 10 relevant methods. We would also need to show its children objects in a way that made the inheritance of methods clear.
For the moment we can assume that all the code is written in C++.
One idea would be to somehow mark the objects we want to document in a way that a system such as doxygen would know what to look at and ignore the rest. Another would be to preprocess the C++ code in such a way as to delete all the non-relevant bits, and document what remains with something like doxygen. (I actually got pretty far with this approach using luadoc, but could not find a way to make luadoc show object hierarchy.)
One thing that might prove helpful is that every Lua object class is registered in a consistent manner, along with its parent class.
There are a growing number of games out there that use Lua for scripting, and many of them have decent documentation. Does anyone have a good suggestion on how to produce it?
PS To clarify, I'm happy to use any tool that will do the job -- doxygen and luadoc are just examples that I am somewhat familiar with.
I have found a solution, which, while not ideal, works pretty well. I cobbled together a Perl script which rips through all the Bitfighter source code and produces a second set of "fake" source that contains only the elements I want. I can then run this secondary source through Doxygen and get a result that is 95% of what I'm looking for.
I'm declaring victory.
One advantage of this approach is that I can document the code in a "natural" way, and don't need to worry about marking what's in and what's out. The script is smart enough to figure it out from the code structure.
If anyone is interested, the Perl script is available in the Bitfighter source archive at https://code.google.com/p/bitfighter/source/browse/luadoc.pl. It is only about 80% complete, and is missing a few very important items (such as properly displaying function args), but the structure is there, and I am satisfied the process will work. The script will improve with time.
The (very preliminary) results of the process can be seen at http://bitfighter.org/luadocs/index.html. The templates have hardly been modified, so it has a very "stock" look, but it shows that things more-or-less work.
Since some commenters have suggested that it is impossible to generate good documentation with Doxygen, I should note that almost none of our inline docs have been added yet. To get a sense of what they will look like, see the Teleporter class. It's not super good, but I think it does refute the notion that Doxygen always produces useless docs.
My major regret at this point is that my solution is really a one-off and does not address what I think is a growing need in the community. Perhaps at some point we'll standardize on a way of merging C++ and Lua and the task of creating a generalized documentation tool will be more manageable.
PS You can see what the markup in the original source files looks like... see https://code.google.com/p/bitfighter/source/browse/zap/teleporter.cpp, and search for #luaclass
Exclude either by namespace (could be class as well) of your C++ code, but not the lua code
EXCLUDE_SYMBOLS = myhier_cpp::*
in the doxygen config file or cherry pick what to exclude by using
/// #cond
class aaa {
...
...
}
/// #endcond
in your c++ code.
I personally think that separating by namespace is better since it reflects the separation in code + documentation, which leads to a namespace based scheme for separation of pure c++ from lua bindings.
Separating via exclusion is probably the most targeted approach but that would involve an extra tool to parse the code, mark up relevant lua parts and add the exclusion to the code. (Additionally you could also render special info like graphs separately with this markup and add them via an Image to your documentation, at least that's easy to do with Doxygen.). Since there has to be some kind of indication of lua code, the markup is probably not too difficult to derive.
Another solution is to use LDoc. It also allows you to write C++ comments, which will be parsed by LDoc and included into the documentation.
An advantage is that you can just the same tool to document your lua code as well. A drawback is that the project seems to be unmaintained. It may also not be possible to document complex object hierarchies, like the questioner mentioned.
I forked it myself for some small adjustments regarding c++. Have a look here.
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
I am currently starting using doxygen to document my source code. I have notice that the syntax is very heavy, every time I modify the source code, I also need to change the comment and I really have the impression to pass too much time modifying the comment for every change I make in the source code.
Do you have some tips to document my source code efficiently ?
Does some editor (or plugin for existing editor) for doxygen to do the following exist?
automatically track unsynchronized code/comment and warn the programmer about it.
automatically add doxygen comment format (template with parameter name in it for example) in the source code (template) for every new item
PS: I am working on a C/C++ project.
Is it the Doxygen syntax you find difficult? Or is it the fact that you have to comment all of the functions now.
If it's the former, there may be a different tool that fits your coding style better. Keep in mind that Doxygen supports multiple commenting styles, so experiment until you find one you like.
If it's the latter, then tough it out. As a good programming practice, every public-facing function should have a comment header that explains:
What the function does
The parameters
The return codes
Any major warnings/limitations about the function.
This is true regardless of the documentation tool you use.
My big tip: Avoid the temptation to comment too much. Describe what you need, and no more. Doxygen gives you lots of tags, but you don't have to use them all.
You don't always need a #brief and a detailed description.
You don't need to put the function name in the comments.
You don't need to comment the function prototype AND implementation.
You don't need the file name at the top of every file.
You don't need a version history in the comments. (You're using a version control tool, right?)
You don't need a "last modified date" or similar.
As for your question: Doxygen has some configuration options to trigger warnings when the comments don't match the code. You can integrate this into your build process, and scan the Doxygen output for any warnings. This is the best way I have found to catch deviations in the code vs comments.
I feel you get back what you put into comments, 5 minutes commenting a class well will in 3 months time when the class needs to be changed by someone else other than the original author (indeed sometimes by the original author) will take much less time to get to grips with.
I second the documentation support mentioned by David, in eclipse when you refactor parameter names it will rename the parameter in your docs section for example. I am not sure I would want it doing anything else automatically to be honest.
"every time I modify the source code, I also need to change the comment" Could be you're documenting too much. You should only have to change the documentation of a function if the change to it requires you to change every caller in some way (or if not actually change, at least check to make sure they weren't relying on obsolete behaviour), of if you're introducing new functionality that a new caller will rely on. So in theory it shouldn't be a massive overhead. Small changes, like optimizations and bugfixes within the function, usually don't need documenting.
There is seriously something wrong about the way you use comments, or how you develop.
Doxygen comments are used for external/internal documentation on interfaces. If your interfaces change extremely fast, then you should probably sit down and think about the architecture layout first.
If you are using doxygen to document the internal flow of functions, then you should maybe rethink this approach (and even then, these comments shouldn't change that much). When you have a function that calculates some value then a comment /// Calculating xy using the abc algorithm is definitely something that shouldn't change each day.
It really depends on how much information you put in your documentation.
My functions generally smaller now due to unit testing and thus the documentation is correspondingly small. Also when documenting the class itself I always have a small snippet of code to show how the class is supposed to use. I find those are the hardest to maintain but worth it so you don't get juniors bugging you asking how they use the class.
Tips:
Only document your public interfaces.
Only do minimal documentation about what the function does.
Try to use an editor that has support (most do) or has a plugin.
You'll be glad when you come to edit your code in 6 months time...
Judge yourself if the below style fits your needs. It is C-affine tho, but maybe you can draw enough from it for your ends.
///\file
/// Brief description goes here
bool /// #retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but
/// #retval 1 will not do so for parameters. (see below)
PLL_start(
unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
/// comment will go also. \n
/// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
/// 2-32767: whatever
int param) ///< 0: crash \n
/// 1: boom \n
/// 2: bang!
{
/**
* Here goes the long explanation. If this changes frequently, you have other more grave problems than
* documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
* - Explain in list form.
* - It really helps the maintainer to grok the code faster.
*
*#attention Explain misuses which aren't caught at runtime.
*
*#pre Context:
* - This function expects only a small stack ...
* - The call is either blocking or non-blocking. No access to global data.
*
*#post The Foobar Interrupt is enabled. Used system resources:
* - FOO registers
* - BAR interrupts
*/
/**#post This is another postcondition. */
}
Use non-documenting comment for new features and early stages of your code. When you find your code is ready to publish, you may update docs. Also avoid repetition of argument or function names.
Use Doxygen's strengths - it will generate class and method descriptions without you adding comments (just not by default - set EXTRACT_ALL=YES).
I don't document every parameter because I think their names should do that for them (*).
I am against the auto-documenting plugins most people recommend because they create generic comments you will then have to maintain.
I want comments to be meaningful - if I see a comment it stands out and I will pay attention.
(*) the exception is when interfaces in public code are very stable and some people will benefit from additional explanations, even then I try to avoid documenting.
Not exactly what you're searching but this Vim plugin can generate Doxygen stub on top of your definitions. It work pretty well.
In my professional software experience, every time a source file is modified, a comment must be entered describing the change. These change comments are usually not in the Doxygen comment areas (unless changes are made to an interface).
I highly suggest you make commenting your code a habit. Not only is this good for when other people have to maintain or assist you with your code, but it helps when you have abandon a source file for a while (such as when management tells you to switch projects). I have found that writing comments as I code helps me understand the algorithms better.
In addition to Doxygen I think you should take a look at Code Rocket.
It actually documents what's happening "inside" your methods by trawling through the actual code and comments they contain - therefore not just limiting itself to the function comment headers, which can get out of date with what the function contents actually are.
It will automatically provide you with flowchart and pseudocode visualizations of your method contents as a form of documentation.
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
I am writing a C++ static library and I have been commenting with doxygen comments in the implementation files. I have never really had to care very much about documentation but I am working on something now that needs to be documented well for the users and also I am trying to replace my previous bad habit of just wanting to code and not document with better software engineering practices.
Anyway, I realized the other day that I need a couple different types of documentation, one type for users of the library(doxygen manual) and then comments for myself or a future maintainer that deal more with implementation details.
One of my solutions is to put the doxygen comments for file, class, and methods at the bottom of the implementation file. There they would be out of the way and I could include normal comments in/around the method definitions to benefit a programmer. I know it's more work but it seems like the best way for me to achieve the two separate types of commenting/documentation. Do you agree or have any solutions/principles that might be helpful. I looked around the site but couldn't really find any threads that dealt with this.
Also, I don't really want to litter the interface file with comments because I feel like it's better to let the interface speak for itself. I would rather the manual be the place a user can look if they need a deeper understanding of the library interface. Am I on the right track here?
Any thoughts or comments are much appreciated.
edit:
Thanks everyone for your comments. I have learned alot from hearing them. I think I have a better uderstanding of how to go about separating my user manual from the code comments that will be useful to a maintainer. I like the idea that #jalf has about having a "prose" style manual that helps explain how to use the library. I really think this is better than just a reference manual. That being said...I also feel like the reference manual might really come in handy. I think I will combine his advice with the thoughts of others and try to create a hybrid.(A prose manual(using the doxygen tags like page, section, subsection) that links to the reference manual.) Another suggestion I liked from #jalf was the idea of the code not having a whole manual interleaved into it. I can avoid this by placing all of my doxygen comments at the bottom of the implementation file. That leaves the headers clean and the implementation clean to place comments useful for someone maintaining the implementation. We will see if this works out in reality. These are just my thoughts on what I have learned so far. I am not positive my approach is going to work well or even be practical. Only time will tell.
I generally believe that comments for users should not be inline in the code, as doxygen comments or anything like that. It should be a separate document, in prose form. As a user of the library, I don't need to, or want to, know what each parameter for a function means. Hopefully, that's obvious. I need to know what the function does. And I need to know why it does it and when to call it. And I need to know what pre- and postconditions apply. What assumptions does the function make when I call it, and what guarantees does it provide when it returns?
Library users don't need comments, they need documentation. Describe how the library is structured and how it works and how to use it, and do so outside the code, in an actual text document.
Of course, the code may still contain comments directed at maintainers, explaining why the implementation looks the way it does, or how it works if it's not obvious. But the documentation that the library user needs should not be in the code.
I think the best approach is to use Doxygen for header files to describe (to the users) how to use each class/method and to use comments within the .cpp files to describe the implementation details.
Well done, Doxygen commenting can be very useful both when reading code and when reading generated HTML. All the difficulty lies in Well done.
My approach is as following:
For users of library, I put Doxygen comments in header files for explaining what is the purpose of that function and how to use it by detailing all arguments, return values and possible side effects. I try to format it such that generated documentation is a reference manual.
For maintainers, I put basic (not Doxygen) comments in implementation files whenever self-commenting code is not enough.
Moreover, I write a special introductory file (apart from the code) in Doxygen format for explaining to new users of libray how to use the various features of the library, in the form of a user's guide which points to details of reference manual. This intro appears as the front page of the Doxygen generated documentation.
Doxygen allows the creation of two versions of the documentation (one for users and one for "internal use") through the \internal command and the INTERNAL_DOCS option. It is also possible to have a finer grained control with conditional sections (see the \if command and the ENABLED_SECTIONS option.)
As others have already noted, it is also useful to provide users (and also maintainers sometimes) something at a higher level than strictly code comments. Doxygen can also be used for that, with the \mainpage, \page, [sub[sub]]section and \par commands
I recommend you to take a look at this paper: http://www.literateprogramming.com/knuthweb.pdf
I normally applied those ideas to my projects (using Doxygen). It also helps in keeping the doc up to date because it is not necessary to leave the IDE, so one can make annotations while coding and, later on, revise the final pdf document to see what needs to be updated or more detailed.
In my experience, Doxygen requires some work so that the pdf look nice, the graphs and pics in place, etc. but once you find your ways and learn the limitations of the tool, it gets the job done quite well.
My suggestion, besides what Kyle Lutz and Eric Malefant have already said, is to put long explanations about related classes in its own file (I use a header file for that) and add references to other parts using Doxygen tags. You only need to include those headers in the Doxygen configuration file (using pattern matching). This avoids cluttering your headers too much.
There is no quick easy answer, good documentation is hard.
I personally feel a layered model is best.
high level docs in prose. Pictures and videos are very appropriate.
reference level docs should Doxygen (well done doxygen, not just off hand comments).
maintainer docs should not show up in the reference docs, but they could still be doxygen as pointed out by by Éric.
I really like the documentation style used in RakNet. The author uses extensive Doxygen comments and provides a generated reference manual. He also provides some plain html tutorials. Best of all he supplies video walk-throughs of some of the more complicated features.
Another good example is SFML. The quality isn't as good as RakNet but it's still very good. He provides a good overview page in the doxygen generated documentation. There are a few plain html tutorials and a plain html Features/Overview page.
I prefer these styles as Doxygen generated documentation is generally too low level when I'm just starting out, but perfectly concise once I'm in the groove.
I often have code based on a specific well defined algorithm. This gets well commented and seems proper. For most data sets, the algorithm works great.
But then the edge cases, the special cases, the heuristics get added to solve particular problems with particular sets of data. As number of special cases grow, the comments get more and more hazy. I fear going back and looking at this code in a year or so and trying to remember why each particular special case or heuristic was added.
I sometimes wish there was a way to embed or link graphics in the source code, so I could say effectively, "in the graph of this data set, this particular feature here was causing the routine to trigger incorrectly, so that's why this piece of code was added".
What are some best-practices to handle situations like this?
Special cases seem to be always required to handle these unusual/edge cases. How can they be managed to keep the code relatively readable and understandable?
Consider an example dealing with feature recognition from photos (not exactly what I'm working on, but the analogy seems apt). When I find a particular picture for which the general algorithm fails and a special case is needed, I record as best I can that information in a comment, (or as someone suggested below, a descriptive function name). But what is often missing is a permanent link to the particular data file that exhibits the behavior in question. While my comment should describe the issue, and would probably say "see file foo.jp for an example of this behavior", this file is never in the source tree, and can easily get lost.
In cases like this, do people add data files to the source tree for reference?
Martin Fowler said in his refactoring book that when you feel the need to add a comment to your code, first see if you can encapsulate that code into a method and give the method a name that would replace the comment.
so as an abstract you could create a method named.
private bool ConditionXAndYHaveOccurred(object param)
{
// code to check for conditions x and y
return result;
}
private object ApplySolutionForEdgeCaseWhenXAndYHappen(object param)
{
//modify param to solve for edge case
return param;
}
Then you can write code like
if(ConditionXAndYHaveOccurred(myObject))
{
myObject = ApplySolutionForEdgeCaseWhenXAndYHappen(myObject);
}
Not a hard and fast concrete example, but it would help with readability in a year or two.
Unit testing can help here. Having tests that actually simulate the special cases can often serve as documentation on why the code does what it does. This can often be better then just describing the issue in a comment.
Not that this replaces moving the special case handling to their own functions and decent comments...
If you have a knowledge base or a wiki for the project, you could add the graph in it, linking to it in the method as per Matthew's Fowler quote and also in the source control commit message for the edge case change.
//See description at KB#2312
private object SolveXAndYEdgeCase(object param)
{
//modify param to solve for edge case
return param;
}
Commit Message: Solution for X and Y edge case, see description at KB#2312
It is more work, but a way to document cases more thoroughly than mere test cases or comments could. Even though one might argue that test cases should be documentation enough, you might not want store the whole failing data set in it, for instance.
Remember, vague problems lead to vague solutions.
I'm not usually an advocate of test driven development and similar styles that stress tests too much, but this seems to be a perfect case where a bunch of unit test can help a lot. And not even in the first place to catch bugs from later changes, but simply to document all the special cases that need to be addressed.
A few good unit test with comments in them are in itself the best description of the special cases. And the commenting of the code itself gets easier too. One can simply point to some unit tests that illustrate the problem that is being solved at that point in the code.
About the
I sometimes wish there was a way to embed or link graphics in the source code,
so I could say effectively, "in the graph of this data set, this particular
feature here was causing the routine to trigger incorrectly, so that's why this piece of
code was added".
part:
If the "graphic" that you want to embed is a graph, and if you use Doxygen, you can embed dot commands in your comment to generate a graph in the documentation:
/**
If we have a subgraph looking like this:
\dot
digraph g{
A->B;
A->C;
B->C;
}
\enddot
the usual method does not work well and we use this heuristic instead.
*/
Don Knuth invented literate programming to make it easy for your program documentation to include plots, graphs, charts, mathematical equations, and whatever else you need to make it understood. A literate program is a great way to explain why something is the way it is and how it got that way over time. There are many, many literate-programming tools; the "noweb" tool is one of the simplest and is shipped with some Linux distributions.
Without knowing the specific nature of your problem is not easy to give an answer, but in my own experience, handling of special cases on hard code must be avoided. Haven't you thought about implementing a rules engine or something like that for handling special cases outside your main processing algorithm?
It sounds like you need more thorough documentation than just code comments. That way someone could look up the function in question in the documentation and be presented with an example picture that requires a special case.