I am trying to determine the best way to use JSDoc 3 to document the attributes and options arguments to a Backbone.Model.
Ideally I'd like to be able to do:
/**
* #class
* #attribute {string} foo the foo attribute
* #attribute {integer} bar the bar attribute
* #option {bolean} baz the baz option
* #option {string} qux the qux option
*/
var MyModel = Backbone.Model.extend({
...
});
However there is no #option tag in JSDoc 3, and #attribute doesn't mean the same thing as a Backbone attribute. In theory I think one could somehow make custom tags like the ones in my pseudo-code, but I couldn't find any existing plug-in with these, and the documentation on how to create custom tags is almost non-existent.
So, since I seem stuck with the built-in tags for now, my question is: what's the next best thing to my pseudo-code (using actual JSDoc 3 tags)?
NOTE: There are several similar questions to this one (How to jsdoc annotate BackboneJS code?, How do I document AMD + Backbone project with JSDoc3) but they all focus on the "big picture" of getting Backbone objects recognized at all. I couldn't find any that specifically addressed the issue of attributes/options.
I eventually found the answer myself in this (non-Backbone-specific) Stack Overflow thread: How to describe "object" arguments in jsdoc?.
To summarize, you can document attributes/options by making an initial parameter (eg. #param attributes), then making a #param attributes.foo or #param options.bar tag. In other words, my pseudo code could be re-done properly with the following syntax:
/**
* #class
* #param {Object} attributes
* #param {string} attributes.foo the foo attribute
* #param {integer} attributes.bar the bar attribute
* #param {Object} options
* #param {boolean} options.baz the baz option
* #param {string} options.qux the qux option
*/
var MyModel = Backbone.Model.extend({
...
});
I still think that it'd be preferable if there was some sort of JSDoc3-Backbone plug-in that allowed #attribute/#option tags, so if one exists and someone posts it as an answer I'll gladly accept that answer instead of my own.
Related
There is a Doxygen option to specify when API appeared using \since tag, for example
///
/// Does foo
///
/// \since 1.5
///
void foo();
And it would appear in foo()'s documentation.
What I'm looking is a way to create automatically page that contains all API
appeared in 1.5 - i.e. list all API marked by \since 1.5 or probably
some other tag if available.
Edit: I tried to use \ingroup and create a group page containing all new API there and it works. But it moves description to this page, for example moves a new method from class definition to a page "New in 1.2.3" which isn't what I wanted.
You want to create an external reference to the current item, an \xrefitem:
\xrefitem version_change_1_0_0 "Since 1.0.0" "Changes in 1.0.0" ...
<key> <heading> <list title> <text>
All items that share the same <key> will be shown on a special generated page. The <heading> will be used to start a section at the place you're using \xrefitem, whereas <list title> will be used as a title for the resulting page (see remarks below). The text can be arbitrary.
The result you get is similar to the lists and appearances of\todo and \bug, and you can even think of \bug and \todo implemented as
\bug <text> = \xrefitem bug "Bug" "List of bugs" <text>
\todo <text> = \xrefitem todo "Todo" "List of todos" <text>
Unfortunately, the key cannot contain dots:
ID "$"?[a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF]*
LABELID [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*
Therefore, you have to use an alias that takes (at least) two arguments, one for the label, and one for the actual text:
ALIASES += sinceversion{3}="\xrefitem version_changes\1 \"Since \2\" \"Changes in \2\" \3\n\n"
ALIASES += sinceversion{2}="\sinceversion{\1,\2,Introduced in this version.}"
If you never use dots, you can of course simplify the alias even more. This will give you two new commands:
\sinceversion{label, version}
\sinceversion{label, version, custom text}
In both cases, the label must only contain alphanumeric symbols, the version can be arbitrary. If you don't provide the custom text, "Introduced in this version" will be shown.
If there's a page with the identifier version_changes<label>, the list of changes will be added. Note that the \page's title will overwrite the title given by the \xrefitem, which can be handy for major releases.
Example
Here's an example of \sinceversion's usage. Note that you probably want to use another alias like ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,X.Y.Z,\1}" if you document a lot of changes for version x.y.z:
Example code
/** Foos around.
* \sinceversion{001,0.0.1}
*/
void foo(){}
/** Bars around.
* \sinceversion{001,0.0.1}
* \sinceversion{002,0.0.2,Removed a memory leak}
*/
void bar(){}
/** \page version_changes002 Changes in 0.0.2
*
* We found several memory leaks and removed them
*/
List of version change pages
List of changes per version
List of changes per version with additional description
Appearance of changes in function documentation
Or do they only affect findElement? For example, if I want to test for an element that does not exist on the page, do I want to use findElement (which will be slow due to implicit waiting), or can I use findElements(..).size() == 0 (for example)?
Yes. Implicit wait is firm to the driver instance and as soon as you instantiate the driver it will apply to any findElement mechanism. Explicit wait is your best bet in terms of waiting for the element since explicit wait does not have influence on the entire driver instance.
Please note Implicit wait also has influence over explicit waits. Mixing them both together is never recommended. See this
I had the same question & found an answer in findElement(By by) documentation (in WebDriver.java).
/**
* Find the first {#link WebElement} using the given method.
* This method is affected by the 'implicit wait' times in force at the time of execution.
* The findElement(..) invocation will return a matching row, or try again repeatedly until
* the configured timeout is reached.
*
* findElement should not be used to look for non-present elements, use {#link #findElements(By)}
* and assert zero length response instead.
*
* #param by The locating mechanism
* #return The first matching element on the current page
* #throws NoSuchElementException If no matching elements are found
* #see org.openqa.selenium.By
* #see org.openqa.selenium.WebDriver.Timeouts
*/
WebElement findElement(By by);
in short:
findElement is affected by the 'implicit wait'
findElement should not be used to look for non-present elements
for non-present elements, use findElements
I'm sure this has already been asked somewhere but I can't seem to find it, so here it goes.
I am creating a program in C and using Doxygen to generate documentation. I am quite satisfied with the results, however the main page has no content. I would like to fill the main page with a list of all functions and structures used in the program in alphabetical order.
I do not know much about Doxygen, beyond the simple tutorial that I have used to get this far. It seems like a task that Doxygen would be able to do, but so far all I have found is instructions on how to create a custom main page.
Is it possible to use Doxygen to automatically generate a list of functions and structures on the main page?
Doxygen doesn't really offer a lot from the configuration point of view. You can use, together with Doxygen and doxyrest, a tool called Sphinx.
Basically, you'll be able to generate XML using Doxygen. Doxyrest is going to convert the XML output into .rst files, while Sphinx will work with the final result (it only handles .rst, that's why you'll need to use an intermediate tool like doxyrest).
Sphinx is going to generate beautiful HTML pages that are easy to read and, more important, to configure.
Information on how to combine these three tools and use them together can be found on this page: https://vovkos.github.io/doxyrest/manual/basic.html
A solution to your problem would be to group your functions using the \addtogroup Doxygen command (add all functions to the same group), and then, using Sphinx, select the newly created group page to be your index/landing page. This can be done by editing some lines in Sphinx's conf.py.
I was also looking for a more elegant way to see and search all functions.
Maybe the following trick will help you that i currently use:
If you use the #todo in your function headers,
then you will get in "Related Pages" a "Todo List" with all function names.
There you will get an alphabetical list with all functions with #todo.
You are also able to klick on the function name for better navigation.
Example/tip: If you view html output with web browser, you are able to search the todo list for function.
I recommend you to use #mainpage. This function changed the header of the main page and then after it you can use functions like #brief for a short information.
Use html tags to create sections, for me it works. Then in the new section with function #see you can go from the main page to functions or files. This is a working excample:
/**
* #mainpage WATCHDOG
* <hr/>
* #setion <b> File tree<b/>
* #brief Here you can see the main files which are used.
* #see io.c
* #see watchdog.c
* #see watchdog.h
* <p/><br/>
* <hr/>
* In this part we have few main functions used by the programm
* <p/><br/>
* #see watchdog_init_s();
* #see fpga_resetregs_init_s();
* #see watchdog_read(int add, unsigned int ws );
* #see watchdog_reset_io_write(WD * watchdog, unsigned int* data,unsigned int *ws );
* <hr/>
*/
When looking at the source code of Angular it seems there is a certain way how to style the comments. A quick google search does not reveal what rules to follow. What are the guidelines?
For example, a comment for a function looks like this:
/**
* when using forEach the params are value, key, but it is often useful to have key, value.
* #param {function(string, *)} iteratorFn
* #returns {function(*, string)}
*/
function reverseParams(iteratorFn) {
return function(value, key) { iteratorFn(key, value); };
}
It starts with a slash (/) and followed by two two asterisks (*) and it has an asterik on every line. Where is that defined? And then there are several #-symbols. Javascript comments starts with /* or //, as described here, so there are some additional styling involved here. I am searching for a description on this....
Ok, I am going to answer this myself. Somebody gave me this link in a comment of an answer that is now deleted. Thanks to you, whoever you are. I am cutting and pasting from this doc:
A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are #param, #return, and #see.
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {#link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* #param url an absolute URL giving the base location of the image
* #param name the location of the image, relative to the url argument
* #return the image at the specified URL
* #see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
Notes:
The resulting HTML from running Javadoc is shown below
Each line above is indented to align with the code below the comment.
The first line contains the begin-comment delimiter ( /**).
Starting with Javadoc 1.4, the leading asterisks are optional.
Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
Notice the inline tag {#link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
If you have more than one paragraph in the doc comment, separate the paragraphs with a paragraph tag, as shown.
Insert a blank comment line between the description and the list of tags, as shown.
The first line that begins with an "#" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.
For more examples, see Simple Examples.
So lines won't wrap, limit any doc-comment lines to 80 characters.
Here is what the previous example would look like after running the Javadoc tool:
getImage
public Image getImage(URL url,
String name)
Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.
This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.
Parameters:
url - an absolute URL giving the base location of the image.
name - the location of the image, relative to the url argument.
Returns:
the image at the specified URL.
See Also:
Image
After seeing this post I tried typing '/**' and I got this in vs code editor
Hit enter and I got like this
however, I don't know whether it is given from vs code extension. I think it is a standard way to comment.
Reading up on the guide for developing maven plugins I see that you can define list parameters and arbitrary object parameters, but is it possible to define a parameter that id a list of objects, defined as:
/**
* #parameter
*/
private List<MyObject> objects;
Sure - I do this all the time. Make sure MyObject is a Java bean with each attribute annotated with #parameter, etc. just as you would if each parameter were in the Mojo itself.
I didn't even annotate anything in MyObject, just list parameter.
#Parameter(property = "versioning.scripts")
private List<MyObject> scripts;
and all is working fine anyway.