I binged or googled for scaladoc 2.0 tutorial or example, I could not find anything, in fact not even a link to official scaladoc 2.0 documentation.
Anyone know where to find one?
docs.scala-lang.org is a more recent source of "Community-driven documentation for Scala" (thanks to the initiative lead by Heather Miller).
(as edited by Martin Konicek in David James's original answer)
The Scaladoc page is quite up-to-date.
Martin Konicek asks in the comment how to make a simple Javadoc-like {#link}.
(And {#link} isn't mentioned in scala.tools.nsc.ast.DocComments.scala)
He mentions that Scaladoc uses [[fullyQualifiedName]] instead of {#link}.
Initial answer (July/Sept 2011)
Right now, the most complete source of information I know about Scaladoc2 is in the new scala-lang.org Wiki.
David James mentions in the comments the Syntax page, and the Tags and Annotations.
The author page has examples, including a what's new section:
Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as Scaladoc may in the future also generate documentation in other formats than HTML.
I wrote a Scaladoc HOWTO over on github here.
It's a how-to written with Scaladoc itself so it serves as an example. I placed extra emphasis on how to get the package documentation to show up in your API, as this is not very clear in the official documentation.
The Scala Style Guide has a nice introductory page on scaladoc. I'd recommend it over the scala-lang.org wiki mentioned in #VonC's answer.
A condensed full example:
/** Creates [[mypackage.Person]] instances, taking a `String` argument. */
object Person {
/** Create a [[mypackage.Person]] with a given name.
*
* This is another paragraph (note the empty line above) containing '''bold''',
* ''italic'', `monospace`, __underline__, ^superscript^, and ,,subscript,,.
*
* Example:
* {{{
* val person = Person("Bill")
* }}}
*
* #param name their name
* #return a new Person instance
*/
def apply(name: String) = {}
}
Note that Scaladoc 2.9 does not support [[links]] to methods (like Javadoc's {#link type#instanceMethod(int, String)} or {#link type.staticMethod()}).
This is the best Scaladoc guide I have found: https://gist.github.com/VladUreche/8396624. It is markdown text, so download it and use a markdown viewer plugin for your browser or paste it into http://markdownlivepreview.com/ to read it.
Related
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.
I may be missing something obvious, but I can't get Scaladoc to link to classes—only to companion objects. Consider these examples.
This works fine:
/** Returns a [[scala.List]] (also known as [[scala.collection.immutable.List]]). */
While this won't link, with Could not find any member to link for "play.api.libs.json.JsObject" logged as a warning:
/** Seems [[play.api.libs.json.JsObject]] is invalid. */
This (taking into account disambiguation syntax), however, will link:
/** Seems [[play.api.libs.json.JsObject$]] is liked. */
I've got external API mappings sorted out in SBT and generated documentation of function signatures links correctly to external site, so I'm (fairly) certain this isn't related to my problem.
Where am I going wrong? (Or is this a bug?)
I'm working with legacy PHP code that has a lot of functions with one-line comments (// ...).
But for documentation generators like doxygen and phpDocumentor to document those functions to the fullest extent, the functions need to be in DocBlock format:
/**
* Summary
*
* Description
*
* #param etc
*/
Does NetBeans provide a way to automatically generate a DocBlock comment given a method signature and / or a one-line comment preceding a function?
Use /** to generate the DocBlock.
I would be looking to customize this "/**" macro shortcut. It would be awesome if I could also find it in the tools.
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.