I'm generating javadoc for the following simple example:
public class test {
/**
* foo does something.
*
* #param x the parameter
*/
public void foo(int x) {}
}
I run javadoc test.java.
I expected x to have the name shown in a non-proportional font, and the description shown in a proportional font, like it happens for the official JDK javadocs for example. Instead I get what shown in this capture:
This is ok for a short description, but it's ugly for longer ones. What am I doing wrong?
When you compare the Java API documentation of Object.equals(obj) for Java 7 and Java 8 you will see the difference in the font for the
Parameters:
obj - the reference object with which to compare.
part. You will see it for all other method’s parameters as well, I just picked the well-known method as an example.
In other words, this is a general change in the behavior of JavaDoc between Java 7 and the current version of Java 8 and you are not doing anything wrong.
If you look into the stylesheet you will find the definition responsible for the description part starting at line 287 containing the attribute font-family:'DejaVu Sans Mono',monospace;.
Related
I am building my first ever Wicket project and I find that the amount of properties files in my code base is growing rapidly. Ideally I would like to contain all internationalization in a single file for each language/region. Just so I can find things easily.
I found out that my application properties file could be ideal for this. My application properties file is called ApiAdminApplication.properties. Now I am trying to add my translatables to this file, without making a mess of things.
According to the javadoc of ComponentStringResourceLoader this should be possible. Apparently the lookup order is as follows:
page1.properties => form1.input1.Required
page1.properties => Required
form1.properties => input1.Required
form1.properties => Required
input1.properties => Required
myApplication.properties => page1.form1.input1.Required
myApplication.properties => Required
The second to last line contains the behavior I am looking for, but cannot get to work.
I have a page called CustomerEditPage which in turn contains a form with id customerForm
So here is what I am adding to ApiAdminApplication.properties, and what I think should work according to the snippet above:
CustomerEditPage.customerForm.name=Customer name
Sadly, this does not work. I can however get this to work by leaving out the page name, and starting with customerForm, but that is not what I want. I want per page internationalization contained in a single file.
Can anyone give me some pointers on this? Thanks.
I think the javadoc of ComponentStringResourceLoader is just wrong and should be fixed.
To accomplish what you need you will need to extend ClassStringResourceLoader and override getResourcePath(). In your impl you will have to prepend the result with the name of the page that owns the Component passed as a parameter.
Then you will need to register your loader at ApiAdminApplication#init() method with:
getResourceSettings().getStringResourceLoaders().add(new MyClassStringResourceLoader(ApiAdminApplication.class))
see the defaults.
Please file a bug report at https://issues.apache.org/jira/projects/WICKET/issues so that the javadoc issue is fixed (or someone else who knows better than me how to accomplish this can explain us).
After reporting the bug I ended up doing what martin-g suggested, and extended ClassStringResourceLoader. For your convenience, here is what I did:
public class PrefixedStringResourceLoader extends ClassStringResourceLoader {
public PrefixedStringResourceLoader(Class<?> clazz) {
super(clazz);
}
protected String getResourcePath(final Component component) {
final Class<? extends Page> parentClass = component.getPage().getClass();
final String resPath = super.getResourcePath(component);
if (!resPath.isEmpty())
return String.format("%s.%s", parentClass.getSimpleName(), resPath);
return parentClass.getSimpleName();
}
}
There is a small gotcha to this. It always requires you to work with complete resource paths. This can be a bit tricky, I had some problems with the snippet below:
<input type="submit" wicket:id="save" wicket:message="value:save" />
This evaluated to CustomerEditPage.customerForm.save.save, where I expected it to become: CustomerEditPage.customerForm.save. This is not the case because the wicket:message actually becomes a child of the save form input.
I ended up going for:
<input type="submit" wicket:id="save" wicket:message="value:caption" />
Which evaluates to CustomerEditPage.customerForm.save.caption, which I find somewhat more readable. Of course, you could roll your own more advanced resource loader, but this one is good enough for me.
I can't determine how to add custom properties or search for them.
Everything I have tried is giving me a Error - #<Google::Apis::ClientError: invalid: Invalid query> when I attempt to search for them. I can successfully complete other queries but I don't know if the client is setup to work with appProperties (or even properties at all).
Basically I just need the correct syntax for searching and adding since it doesn't appear to be in the documentation.
Assuming you already have a reference to an authorized DriveService, you can search based on appProperties using a q-parameter (documented here), like this:
file_list = drive.list_files(
q: "appProperties has { key='my_app_key' and value='my_val' }",
fields: 'files(id, name, appProperties)',
spaces: 'drive')
If you omit the fields parameter then the search will still work but the properties themselves won't be returned.
Updating appProperties is definitely arcane and the documentation is opaque. What you need is the ID of the file, and a File value object as a container for the attributes to update. Something like this:
new_app_properties = { 'my_app_key' => 'my_val' }
update_f = Google::Apis::DriveV3::File.new(app_properties: new_app_properties)
drive.update_file(file_id, update_f)
When I document my methods in PDT Eclipse, if the return of a method might be an array, it generates the following kind of documentation / type hinting:
* #return multitype:Ambigous <\CodeBase\Node\DataNode, NULL>
I have looked for this documentation and found a few good ones, but nothing good on the "multitype" and "Ambiguous".
Is there any documentation which covers how to best make use of this in order to use the type hinting? Is it maybe possible to define the array structure returned: e.g. that the returned array contains a string key and a certain kind of object - would be useful for "foreach" loops?
PDT since 3.6 (Mars.1) no longer generate multitype / amiguous and follow phpdoc standard:
multitype:ClassName => ClassName[]
Amiguous< ClassName,ClassName2 > => ClassName|ClassName2
See also:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=467148
https://bugs.eclipse.org/bugs/show_bug.cgi?id=467151
Here is an example of the problem. This is the implementation of a static method Add defined within a class foo.
/// <summary>
/// Adds two or three numbers together.
/// </summary>
/// <param name="x">First number</param>
/// <param name="y">Second number</param>
/// <param name="z">Third number - optional - defaults to 0 if set to null.</param>
System::Double foo::Add(
System::Double x,
System::Double y,
System::Nullable<System::Double> z)
{
System::Double output = x + y;
if (z.HasValue)
output = output + z.Value;
return output;
}
I have used /doc when compiling this code fragment using C++ with the /clr option.
Subsequently xdcmake is used to produce an XML file.
The XML file looks OK - the automatic description of the parameters looks like this:
Add(System.Double,System.Double,System.Nullable`1{System.Double})
followed by the summary and param tags defined in the code above.
However when I use the resulting .NET assembly within C# (Visual Studio 2010) I don't see any documentation for this function in the Object Browser (the entire function has no documentation, not just the nullable parameter z).
For functions without nullable inputs there is no problem and I see the list of parameters and summary in the Object Browser as I would have hoped.
Any ideas about what I need to do to fix this?
I managed to solve the problem today. From looking at the C# manual via http://www.microsoft.com/en-us/download/confirmation.aspx?id=7029 I saw that xdcmake was generating the wrong XML for nullable parameters. The `1 was not required.
The XML entry for the Add function with a nullable parameter should be:
Add(System.Double,System.Double,System.Nullable{System.Double})
instead. Quote from the manual (from section A.3.1 of the C# language specification version 5.0):
Arguments that refer to constructed generic types are encoded using
the generic type, followed by “{“, followed by a comma-separated list
of type arguments, followed by “}”.
I am writing a Grails (2.3.3 currently) application and have created a validateable command object similar to the following:
#Validateable
class MyCustomCommand {
String name
static constraints = {
name blank: false
}
}
In my i18n/messages.properties file I defined the following properties to override the default error messages.
MyCustomCommand.name.blank=Name must be provided.
MyCustomCommand.name.null=Name must be provided.
Which per the Grails documentation should be of the format [Class Name].[Property Name].[Constraint Code] as I have done. When I run my application if I leave the value blank I still get the default message for a null property.
I also tried following the example of the default messages and defining them a follows, but still get the default message.
MyCustomCommand.name.blank.message=Name must be provided.
MyCustomCommand.name.null.message=Name must be provided.
I am assuming that I am missing something simple here, but have yet to stumble upon what. Any suggestions on what I am doing incorrectly?
It is simple indeed. Message should look like:
myCustomCommand.name.blank=Name must be provided.
myCustomCommand.name.nullable=Name must be provided.
//className.propertyName.blank (camelCase with first letter of class name lower)
So, as I anticipated it was something simple. I was using the defaults as an example which used null where as what I really needed was nullable. Which does make sense as that matches the constraint name.
Therefore the correct version is:
myCustomCommand.name.blank=Name must be provided.
myCustomCommand.name.nullable=Name must be provided.