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.
Related
I'm trying to setup jsdoc in my codeing. The files are like the image bellow. The module is actaually the folder skeleton. What do I need to add to the two class.js files to get them included in my module generated with jsdoc?
Right now it is generated like this. It doesn't contain the information of the classes.
If I move my comment block from to my class files I get the image bellow, and if I place it in both files all info is duplicated.
The comment block I have is this
/**
* Module defining the database structure. This module contains all table models as well as any validations or functions related to those models.
* #module Skeleton
* #author E. Koster
* #version 1.0.0
* #since 2.0.0
*/
I found it, it's #memberOf module:MODULE_NAME what I was looking for.
I am working on a library of mathematical functions. As part of the Scaladoc, I would like to include the formula of each function. E.g.
/**
* Sum squared function:
* \(f(x) = \sum_i^n x_i^2\)
*/
def sumSquared[T](x: Seq[T]) = x.map(xi => xi * xi).sum
I am using MathJax to display the formula. It works if I manually edit the generated html to include the required MathJax javascript, but I want to automate this.
So far the only solutions I've found are:
Is there a way to include math formulae in Scaladoc?
How to run bash script after generating scaladoc using doc task?
If these are the only options then okay, however I'd like do this using only sbt (no external scripts). Is there a way to do this by maybe setting scalacOptions as in How to ScalaDoc?
I added an answer to Is there a way to include math formulae in Scaladoc? with an sbt task that does the job, but still using MathJax.
I don't know of any code that would actually replace the latex formula to images in the generated api files
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.
I am trying to use Doxygen Automatic link generation to document some enum types. However, it is not generating links for the global enum types. It does generates links for the global struct types. Is there something I am missing? I am using the example provided on the link above. As required, I have documented the file in which the types are defined.
update1: I am using Doxygen version 1.6.3
update2: global structs are ok
Yeah, I had that same issue; i think doxygen thinks they are private or something stupid like that. Try using the \public. Don't forget to do the /*! on the first line
/*! \public
* Enum description goes here
*/
typedef enum {
/**
* Printer control language ZPL
*/
PRINTER_LANGUAGE_ZPL,
/**
* Printer control language CPCL
*/
PRINTER_LANGUAGE_CPCL
} PrinterLanguage;
I was having the same issue. Some header files generated a link for enums and other header files did not. You must explicitly document the file.
Here is a excerpt from this page int the documentation.
http://www.doxygen.nl/manual/docblocks.html#memberdoc
To document a global C function, typedef, enum or preprocessor
definition you must first document the file that contains it (usually
this will be a header file, because that file contains the information
that is exported to other source files).
Attention
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must
document the file in which they are defined. In other words, there
must at least be a
/*! \file */
or a
/** #file */
line in this file.
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!