Posted by
Adrian Daerr-2 on
Apr 14, 2009; 8:54pm
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692793.html
> I had a look at your javadoc
Thanks.
> (at this stage, you should offer links to .java files, really).
I did say how to obtain the .java files, and there were links as well
from within the javadoc; here are the direct links:
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.javahttp://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get_help_for_PlugIn.java> You use Java5-style Java templates. That is nice, but makes sure that it
> will not be included in ImageJ anytime soon; ImageJ's minimum Java version
> is 1.4 (due to use of the MouseWheelListener).
The main suggestion at this stage is to add to ImageJ an interface
ij.plugin.PlugInDoc. I wrote it with Java5 templates:
public interface PlugInDoc {
public java.util.Map<String,String> getDocumentation();
}
(should have stated more clearly that it boils down to that)
but making it Java 1.4 compatible is really not an issue, here you are:
public interface PlugInDoc {
public java.util.Map getDocumentation();
}
:-)
The rest (i.e. the plug-in Get_doc_for_PlugIn) at this stage was just
meant to show how this can be used, and is not necessarily meant to go
into ImageJ. It can also be made 1.4-compatible however, and will
certainly be if the interface is accepted into ImageJ.
> Besides, it would be better if you defined the interface like this:
>
> String getDocumentation(String field);
OK, advantages: probably somewhat simpler to use, no Map required. But
unless you provide also a method which returns possible field values,
you cannot know whether a given field value exists. You have to try, and
hope authors consistently react to unknown fields (which will never be
the case, some will return 'null', others an empty String, others will
think returning a default usage text in this case is a good idea, ...).
And what if we want to show all the documentation there is ?
So I would conclude we need to add something like
public String[] getDocKeys();
or
public java.util.Set getDocKeys();
at which point the work for the plug-in author becomes bigger than
writing the one line to create the LinkedHashMap.
> rather than having to construct a complete Map, often only for a single
> value.
>
> And then, with this interface having free-form identifiers, IMHO you do
> not buy much over the "about" you mentioned yourself: Nobody needs to
> handle all of the interesting identifiers.
>
> Rather, I'd like to have getAuthor(), getReleaseDate(), getWebsite(), and
> then probably getExtra(String identifier);
That's indeed another plausible alternative. The reasons why I think the
"Map" approach (or your field access method above) is better are:
1) "having to construct a complete Map, often only for a single value",
as you say, does not seem so bad to me at all,
Map doc = new LinkedHashMap();
doc.put("About","Here some text");
is not much longer than
String docAbout = "Here some text";
(and the map is only created once, so there is only one additional line
alltogether)
Performance is not an issue either.
2) The convenience of a Map structure is well worth the one line to
create it: without any more work by the plug-in author, the
Map-interface provides methods to check for the presence of certain
information, iterators over all fields, ...
2) Nothing prevents the documentation of the interface from
standardizing a number of identifiers for common information, recommend
the presence of a number of them, or even make some fields mandatory
(although I personnally don't like this latter idea too much). And
documentation can adopt new emerging standard fields, whereas methods
cannot be added or removed.
3) Making a list of separate methods (getAuthor(), getReleaseDate(),
getWebsite(),...) doesn't guarantee any better than that those methods
are really filled with sensible values, and make the whole interface
heavier. Authors might not care at all to put a Website or a release
date. The Map approach is like saving preferences in a Preferences
structure instead of providing a zillion access methods: proper
documentation is of course the key.
> At least that way you are guaranteed to have more information than you
> have now.
I would say the opposite, there is neither a guarantee, nor more
information. The information is the same, but the writing as well as the
access is more cumbersume with a lot of methods. If the Map-interface
documentation says there should be fields "author", "releaseDate" etc,
the plug-in author can ignore it, but so can he write
getReleaseDate() { return null; } in case the interface forces him to
implement that method.
In both cases we have to check whether we have the information, so
hardly anything is gained.
Thanks a lot for the comments. You are right about the fact that it is
interesting to be able to get specific information (author, ...) in a
standardized way. I did not take this into account in my suggestion. I
think however that it is sufficient to just to reserve/document/require
specific keywords for fields in a simple Map- (or map-like) interface,
and avoid forcing the author to implement a multiplicity of methods.
Hoping for more discussion,
best regards,
Adrian