The company I'm working for does not use Doxygen, and in their coding standard explicitly prohibits "parseable comment styles such as javadoc, etc".
However, I've still found it very useful to run Doxygen myself just so I can see the class structure, and get nice per-class documentation of all the methods the a class has, including inherited ones.
The company does document the classes in the header files, with simple comments above each method declaration. It would be very useful if I could configure Doxygen to treat these comments as the function descriptions, even though they don't start with any Doxygen markers.
So: is it possible to get Doxygen to treat comments on the line above declarations as if they are the description for that item even when the comment is not marked with Doxygen's "parse this comment" markers?
The next best thing is to click on the #include <foo.h> links at the top of the class file to jump to the file itself, which I have been using. That doesn't help for seeing all of a derived class's methods in one place, though.
When the comments above the methods have only "normal" comments i.e. with /* or // the best thing to do would be that you write a small filter (see e.g. INPUT_FILTER with sed or awk or ... ) in which you convert (all?) /* / // comments into /** / /// so the comment blocks are parsed by doxygen. The result is not as nice as with "full" doxygen comments.
It is just a workaround and can lead to unexpected results when the INPUT_FILTER does not exclude e.g. // inside strings from consideration.
Related
When I check the code from packages I see they use both // and /// to comment.
// is a normal comment.
/// is a highlighted comment.
It seems like using /// is better, so why do they using both of them? And does it make the app slower when using comments in Dart?
DO use /// doc comments to document members and types.
Using a doc comment instead of a regular comment enables dartdoc to find it and generate documentation for it.
Example:
/// The number of characters in this chunk when unsplit.
int get length => ...
See the official guide here.
For historical reasons, dartdoc supports two syntaxes of doc comments: /// (“C# style”) and /** ... */ (“JavaDoc style”). We prefer /// because it’s more compact. /** and */ add two content-free lines to a multiline doc comment. The /// syntax is also easier to read in some situations, such as when a doc comment contains a bulleted list that uses * to mark list items.
If you stumble onto code that still uses the JavaDoc style, consider cleaning it up.
do it make the app slow when using comment in Dart?
No, dart compiler will remove them from the release build.
First it's not affect on speed of your codes, the complier just igonre it, it's for you and for other developers.
Second, // it's just a normal comment for normal text or code you don't use for now. But /// it's used for document your code and explain what your function or code is supposed to do.
You can read full DartDoc from http://dartdoc.takyam.com/articles/doc-comment-guidelines/
I've just started using doxygen to document some legacy C code and I'm very impressed about what in can do even with un-marked up code. I've gotten the basics, annotating routines: brief, description, param, return, see, etc. That all appears (beautifully) in the generated documentation for the function. My question is: Can I put doxygen markup inside the routine, interspersed in the actual code, so comments that explain the "upcoming" section of code, can also be included in the documentation. Providing a stepwise overview of what the function does without having to copy those comments to the top of the routine?
I've got a setup where I use doxygen to describe a set on unit tests (I use QtTest to run the tests). The output from the tests are parsed by a little Python snippet that produces a nice and tidy report. Now, I'd love to link from the report to each test case, i.e. private slot member method, in the doxygen material. However, the anchors defined by doxygen looks like this:
<a class="anchor" id="a2a0e066d4dad8e0dff6c9231bf65fd65"></a>
<!-- doxytag: member="PRadioTunerTst::scanFM" ref="a2a0e066d4dad8e0dff6c9231bf65fd65" args="()" -->
Sure, I could parse the doxygen html and match all method to the reference key, but I'd much rather have readable links. I do not overload any unit test case methods, so having them enumerated would not be an issue - I'd simply be able to pick the first and only. I'd even be happy to calculate the id hash myself. I just need to know how to.
So, basically, the questions is:
Does anyone know how to tune doxygen
to generate readable anchors
if not, how do I calculate the hash?
Instead of trying to reconstruct the hash (which is a md5 checksum over the method's definition as parsed by doxygen, see MemberDef::setAnchor() in the code). I would suggest to let doxygen generate a tag file (GENERATE_TAGFILE) and then parse that. The tag file is a simple XML file which has both the name and the anchor for each member.
I also needed link targets, in my case for rst docs to point at breathe/doxygen-created html. Here's what I did:
To better understand how doxygen creates anchors, I recompiled doxygen, with this at the end of setAnchor():
printf("memAnchor=%s sigStr=%s\n", memAnchor.data(), sigStr.data());
, which creates output like:
memAnchor=const int SomeNamespace::GetStateGetState(SomeNamespace::State *state) sigStr=f2c41a8a6a152602c92fefb80bd0862a
I already had my function signatures, so I created strings similar to memAnchor above and piped it through md5sum to get the hash, then appended it to the string which is common to all anchors. In my rst doc, I then put definitions like:
.. _GetState: `project0class_SomeNamespace_1f2c41a8a6a152602c92fefb80bd0862a`_
Not sure on the first question about readable anchors.
I am building a Qt based project, and many Qt classes are found in the target documentation.
How can I tell Doxygen to disable documentation generation for some classes? For Q.*?
Working under the assumption that what you have is something like this: (The question is a little unclear in this regard)
/**
* Some documentation for class X
*/
class X: public osg::Drawable {
...
}
And your problem is that you want to include documentation for class X, but not for class osg::Drawable, the proper technique is to use EXCLUDE_SYMBOLS. For example, in the case above use
EXCLUDE_SYMBOLS = osg::Drawable
If you want to be slightly more rigorous, you can use
EXCLUDE_SYMBOLS = osg::Drawable \
Drawable
Wild-cards are also allowed, so this will also work
EXCLUDE_SYMBOLS = osg::*
If \internal tag does not work, you can try \cond ... \endcond tags for marking a portion of code to be hidden from Doxygen.
EDIT
If you want to exclude specific files, you can use EXCLUDE_PATTERNS variable in Doxyfile configuration file.
Its not the best way but one can mark some portion of the documentation (class, members, ...) with the private. This prevents the piece of code from being included in the output documentation. (I use this to hide copy/move constructors/operators from appearing in the API documentation.)
/*!
* \brief This is included.
*/
class API
{
public:
/*!
* \brief So is this.
*/
API() noexcept;
/// \private
~API() noexcept; /* But this not, though technically public. */
private:
int m_version; /* This is not either. */
}
One should note though that this is a Doxygen extension for PHP, which according to the documentation they should not be used.
For PHP files there are a number of additional commands, that can be used inside classes to make members public, private, or protected even though the language itself doesn't support this notion.
The other option is to use the solution mouviciel provided, but it requires at least two lines.
Though not the correct answer for the detailed question it might be helpful for readers of the question title (like me). It works for classe too!
I'm a big fan of GhostDoc's automatic comment generation in Visual Studio so am looking for an plugin that does the same job with my Java code in Eclipse. Any recommendations?
You can check JAutodoc (http://jautodoc.sourceforge.net/)
From the author:
JAutodoc is an Eclipse Plugin for
automatically adding Javadoc and file
headers to your source code. It
optionally generates initial comments
from element name by using Velocity
templates for Javadoc and file
headers.
This one is the one I've found closest to GhostDoc.
It is basically the equivalent of Javadoc, which can be generating in eclipse with the shortcut:
ALT+Shift+J
(when you are within the Java function you wish to add javadoc for)
From there, if you really want XML format, you can try and use a JELDoclet
GhostDoc has a nice extra feature that infers a description of what the method does by parsing the method name and providing this as skeletal documentation. For example, using GhostDoc on a method named GetDocumentName() might return the phrase "Gets the document name". While this is hardly more information than provided by the method name, it adds method documentation where previously none existed. Some might argue that this is barely useful. I argue to the contrary because it supports generating documentation from the source code (e.g., for tools like NDoc or SandCastle).
In my opinion the greatest benefit of GhostDoc over eclipse's "Generate Element Comment" is that it encourages programmers to begin adding documentation comments by adding an extremely fast and reliable way create this. The programmer can accept the inferred text, (suitable in 50 - 80% of cases), or expand on this for more complex methods. For the junior programmer who is not as familiar with how documentation comments are used, this can quickly shorten the learning curve and encourage good programming practices.
Javadoc is not like GhostDoc my friend. Javadoc only creates the structure so one can write the documentation from scratch. GhostDoc actually fills up the information according to the Method/Property name.
Example:
/// <summary>
/// Gets the user from id.
/// </summary>
/// <param name="id">The id.</param>
/// <returns></returns>
private string GetUserFromId(string id);
JAutoDoc is the closest I've found so far but it's not as magical as GhostDoc.
Never used GhostDoc, so not sure what extra functionality it gives, but if it's about generating type and method comments based on the name, parameters, return type etc. then eclipse has it built in, so no extensions needed.