an interface to encourage self-documentation of plug-ins

[Adrian Daerr-2]

Dear ImageJ-users,

One of the factors limiting the re-use of the many high quality plug-ins
that exist for ImageJ is in my opinion the lack of documentation (there
are other factors of course). When documentation exists, it is not
always clear where to find it: in the source, on a web-page, ... ?
I think it might be worth trying to define an interface that would allow
and encourage plug-in authors to put any information they might judge
usefull in the view and reach of the users. There has been a weak
tradition of printing some information when the argument to the
PlugIn.run() method is "about", but this was to my knowledge never
really exploited to get information on installed plug-ins, and requires
programming time for anything beyond IJ.log() statements.

In order to launch the discussion, and draw comments and criticism, I
sketched a first attempt at an idea of a documentation interface. I
would very much like to know whether others think this might be a good
idea, whether those writing plug-ins would consider actually using such
a framework, and what could be better.

If you just want to know what I have in mind before reading on, please
consider installing the two class files

http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.class
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get_help_for_PlugIn.class

somewhere in your plugin directory, restart ImageJ and try the
'Get_help_for_PlugIn' plug-in that appeared (if you prefer java files,
just change the extensions in the URLs above from .class to .java). The
current version requires Java >= 1.6 to run (and compile; but it is not
a fundamental problem to back-port this to earlier Java versions).

Or have a look at
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html

For the moment the choice you'll be presented with when running the
plug-in is limited to the plug-in itself, which self-documents when you
click 'ok'. You can have it open the javadoc API, the source code, etc
by checking the boxes in front of the ressources. Is this (i.e. text and
arbitrary URIs) powerful enough ? (obviously the presentation can be
much more fancy, this is just meant to be a proof-of-concept)

Back to the idea, which was to have some lightweight scheme (we can't do
  much about the fact that writing documentation is work, but exposing
the information present (in the source, a publication or anywhere on the
internet) to the user should not cost the programmer more than a few
seconds): in addition to the usual PlugIn or PlugInFilter interface, the
plug-in wishing to expose documentation implements a new PlugInDoc
interface, which is defined simply as:

public interface PlugInDoc {
     public java.util.Map getDocumentation();
}

and the programmer has to fill in one single method. I hope the examples at
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
show what I had in mind: writing this method is no harder than any
usage() or about() method delivering only a String, yet quite flexible
and not restrictive.

In this basic version a plug-in is used to inspect other plug-in's
documentation, but there is no obstacle to creating an "about..."
sub-menu containing a replica of the "plugins" menu to directly inspect
the documentation/usage information/update information/... I think there
there is a potential for making plug-ins much easier to use.

Hoping for reactions,
best regards
Adrian

[dscho]

Hi,

On Tue, 14 Apr 2009, Adrian wrote:

> One of the factors limiting the re-use of the many high quality plug-ins
> that exist for ImageJ is in my opinion the lack of documentation (there
> are other factors of course). When documentation exists, it is not
> always clear where to find it: in the source, on a web-page, ... ?
>
> I think it might be worth trying to define an interface that would allow
> and encourage plug-in authors to put any information they might judge
> usefull in the view and reach of the users. There has been a weak
> tradition of printing some information when the argument to the
> PlugIn.run() method is "about", but this was to my knowledge never
> really exploited to get information on installed plug-ins, and requires
> programming time for anything beyond IJ.log() statements.

I had a look at your javadoc (at this stage, you should offer links to
.java files, really).

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).

Besides, it would be better if you defined the interface like this:

        String getDocumentation(String field);

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);

At least that way you are guaranteed to have more information than you
have now.

Ciao,
Dscho

[Adrian Daerr-2]

> 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.java
http://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

[Burger Wilhelm]

Hello Adrian,

I fully agree that the lack of documentation is a notorious problem.
However, I also agree with Johannes that - unless tags are standardized
and enforced - the gain will be small. Also, for typing documentation
texts I would certainly prefer a more flexible style than having to
concatenate individual string elements.

But why invent something new? Javadoc is designed for exactly that and
is a well-known and standardized mechanism, provides HTML or custom
formatting, element highlighting etc. I guess it should be possible to
extract the documentation from a plugin's source file and display it on
the fly (and cache for later use). The plugin interface need not change
at all and plugin writers would just have to write standard comments.

--Wilhelm

> -----Original Message-----
> From: ImageJ Interest Group [mailto:[hidden email]] On
> Behalf Of Adrian
> Sent: Tuesday, April 14, 2009 6:29 AM
> To: [hidden email]
> Subject: an interface to encourage self-documentation of plug-ins
>
> Dear ImageJ-users,
>
> One of the factors limiting the re-use of the many high
> quality plug-ins
> that exist for ImageJ is in my opinion the lack of
> documentation (there
> are other factors of course). When documentation exists, it is not
> always clear where to find it: in the source, on a web-page, ... ?
> I think it might be worth trying to define an interface that
> would allow
> and encourage plug-in authors to put any information they might judge
> usefull in the view and reach of the users. There has been a weak
> tradition of printing some information when the argument to the
> PlugIn.run() method is "about", but this was to my knowledge never
> really exploited to get information on installed plug-ins,
> and requires
> programming time for anything beyond IJ.log() statements.
>
> In order to launch the discussion, and draw comments and criticism, I
> sketched a first attempt at an idea of a documentation interface. I
> would very much like to know whether others think this might
> be a good
> idea, whether those writing plug-ins would consider actually
> using such
> a framework, and what could be better.
>
> If you just want to know what I have in mind before reading
> on, please
> consider installing the two class files
>
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Plu

gInDoc.class
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get
_help_for_PlugIn.class

>
> somewhere in your plugin directory, restart ImageJ and try the
> 'Get_help_for_PlugIn' plug-in that appeared (if you prefer
> java files,
> just change the extensions in the URLs above from .class to
> .java). The
> current version requires Java >= 1.6 to run (and compile; but
> it is not
> a fundamental problem to back-port this to earlier Java versions).
>
> Or have a look at
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
>
> For the moment the choice you'll be presented with when running the
> plug-in is limited to the plug-in itself, which
> self-documents when you
> click 'ok'. You can have it open the javadoc API, the source
> code, etc
> by checking the boxes in front of the ressources. Is this
> (i.e. text and
> arbitrary URIs) powerful enough ? (obviously the presentation can be
> much more fancy, this is just meant to be a proof-of-concept)
>
> Back to the idea, which was to have some lightweight scheme
> (we can't do
>   much about the fact that writing documentation is work, but
> exposing
> the information present (in the source, a publication or
> anywhere on the
> internet) to the user should not cost the programmer more than a few
> seconds): in addition to the usual PlugIn or PlugInFilter
> interface, the
> plug-in wishing to expose documentation implements a new PlugInDoc
> interface, which is defined simply as:
>
> public interface PlugInDoc {
>      public java.util.Map getDocumentation();
> }
>
> and the programmer has to fill in one single method. I hope
> the examples at
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
> show what I had in mind: writing this method is no harder than any
> usage() or about() method delivering only a String, yet quite
> flexible
> and not restrictive.
>
> In this basic version a plug-in is used to inspect other plug-in's
> documentation, but there is no obstacle to creating an "about..."
> sub-menu containing a replica of the "plugins" menu to
> directly inspect
> the documentation/usage information/update information/... I
> think there
> there is a potential for making plug-ins much easier to use.
>
> Hoping for reactions,
> best regards
> Adrian
>

[dscho]

Hi,

On Wed, 15 Apr 2009, Burger Wilhelm wrote:

> I fully agree that the lack of documentation is a notorious problem.
> However, I also agree with Johannes that - unless tags are standardized
> and enforced - the gain will be small. Also, for typing documentation
> texts I would certainly prefer a more flexible style than having to
> concatenate individual string elements.
>
> But why invent something new? Javadoc is designed for exactly that and
> is a well-known and standardized mechanism, provides HTML or custom
> formatting, element highlighting etc. I guess it should be possible to
> extract the documentation from a plugin's source file and display it on
> the fly (and cache for later use). The plugin interface need not change
> at all and plugin writers would just have to write standard comments.

As far as I can tell, Javadoc was not meant to generate documentation for
users, but documentation for developers (such as the J2SE API).

Indeed, without the source code, you cannot extract the information from a
plugin using javadoc.

Ciao,
Dscho

[Jean-Yves Tinevez-4]

On Apr 15, 2009, at 1:23 PM, Burger Wilhelm wrote:

> Hello Adrian,
>
> I fully agree that the lack of documentation is a notorious problem.
> However, I also agree with Johannes that - unless tags are  
> standardized
> and enforced - the gain will be small. Also, for typing documentation
> texts I would certainly prefer a more flexible style than having to
> concatenate individual string elements.
>
> But why invent something new? Javadoc is designed for exactly that and
> is a well-known and standardized mechanism, provides HTML or custom
> formatting, element highlighting etc. I guess it should be possible to
> extract the documentation from a plugin's source file and display it  
> on
> the fly (and cache for later use). The plugin interface need not  
> change
> at all and plugin writers would just have to write standard comments.
>
> --Wilhelm

Hi Wilhelm,

We cannot mix developer documentation and use documentation.
The developer documentation should be generated by javadoc, but it  
documents the metods and fields within the plugin, which is generally  
f little use to the common user.
What Adrian proposes is a way to embed user documentation within  
the .java file, that is how to use the plugin, not how it is written.

cheers
jy

[Burger Wilhelm]

> From: ImageJ Interest Group [mailto:[hidden email]] On
> Behalf Of Jean-Yves Tinevez


> Hi Wilhelm,
>
> We cannot mix developer documentation and use documentation.

Well, why not?

The line between "developers" and "users" is blurred, since plugins are
not only invoked via the menu but also used from other programs or
scripts. With javadoc, one can place general user information about the
use of the plugin and its parameters etc. upfront. Then, as far as the
implementation goes, javadoc only shows the exposed (public) members of
an API. If a plugin has many of these, they are either relevant for
other developers/users or should not be exposed at all. (I suppose
fields should never be public anyway.)

In this sense, I would actually find it quite attractive to have both
user plus API documentation together in the same place.


> The developer documentation should be generated by javadoc, but it  
> documents the metods and fields within the plugin, which is
> generally of little use to the common user.
> What Adrian proposes is a way to embed user documentation within  
> the .java file, that is how to use the plugin, not how it is written.

I know. Of course (as Johannes noted) the source file must be available
for this at some point.

--Wilhelm

[Paul Johnston]

Adrian,

I think your idea is a good one.  I agree with Johannes that the Map
interface is too "loose", I would prefer specifically named
getters/setters.  However, I'm not sure this is a problem that's best
solved at the .class level.  Rather, having a centrally hosted plugin
registry and a package-manager like system for installing ImageJ
plugins would be much better.  Then, developers could be required to
conform to a standardized submission template (in xml or something
like that (I hate Java @attribute declarations personally)), and
documentation be automatically available via that mechanism.

Just my two cents. (My apologies if this idea has been discussed
before, I have not been following the list for too long).

Paul

On Mon, Apr 13, 2009 at 9:28 PM, Adrian
<[hidden email]> wrote:

> Dear ImageJ-users,
>
> One of the factors limiting the re-use of the many high quality plug-ins
> that exist for ImageJ is in my opinion the lack of documentation (there are
> other factors of course). When documentation exists, it is not always clear
> where to find it: in the source, on a web-page, ... ?
> I think it might be worth trying to define an interface that would allow and
> encourage plug-in authors to put any information they might judge usefull in
> the view and reach of the users. There has been a weak tradition of printing
> some information when the argument to the PlugIn.run() method is "about",
> but this was to my knowledge never really exploited to get information on
> installed plug-ins, and requires programming time for anything beyond
> IJ.log() statements.
>
> In order to launch the discussion, and draw comments and criticism, I
> sketched a first attempt at an idea of a documentation interface. I would
> very much like to know whether others think this might be a good idea,
> whether those writing plug-ins would consider actually using such a
> framework, and what could be better.
>
> If you just want to know what I have in mind before reading on, please
> consider installing the two class files
>
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.class
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get_help_for_PlugIn.class
>
> somewhere in your plugin directory, restart ImageJ and try the
> 'Get_help_for_PlugIn' plug-in that appeared (if you prefer java files, just
> change the extensions in the URLs above from .class to .java). The current
> version requires Java >= 1.6 to run (and compile; but it is not a
> fundamental problem to back-port this to earlier Java versions).
>
> Or have a look at
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
>
> For the moment the choice you'll be presented with when running the plug-in
> is limited to the plug-in itself, which self-documents when you click 'ok'.
> You can have it open the javadoc API, the source code, etc by checking the
> boxes in front of the ressources. Is this (i.e. text and arbitrary URIs)
> powerful enough ? (obviously the presentation can be much more fancy, this
> is just meant to be a proof-of-concept)
>
> Back to the idea, which was to have some lightweight scheme (we can't do
>  much about the fact that writing documentation is work, but exposing the
> information present (in the source, a publication or anywhere on the
> internet) to the user should not cost the programmer more than a few
> seconds): in addition to the usual PlugIn or PlugInFilter interface, the
> plug-in wishing to expose documentation implements a new PlugInDoc
> interface, which is defined simply as:
>
> public interface PlugInDoc {
>    public java.util.Map getDocumentation();
> }
>
> and the programmer has to fill in one single method. I hope the examples at
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
> show what I had in mind: writing this method is no harder than any usage()
> or about() method delivering only a String, yet quite flexible and not
> restrictive.
>
> In this basic version a plug-in is used to inspect other plug-in's
> documentation, but there is no obstacle to creating an "about..." sub-menu
> containing a replica of the "plugins" menu to directly inspect the
> documentation/usage information/update information/... I think there there
> is a potential for making plug-ins much easier to use.
>
> Hoping for reactions,
> best regards
> Adrian
>

[dscho]

Hi,

On Wed, 15 Apr 2009, Paul Johnston wrote:

> having a centrally hosted plugin registry and a package-manager like
> system for installing ImageJ plugins would be much better.

Actually, this is one of the missions of Fiji.  Stay tuned.

> Then, developers could be required to conform to a standardized
> submission template (in xml or something like that (I hate Java
> @attribute declarations personally)), and documentation be automatically
> available via that mechanism.

If you force developers to work more, you will lose them.

Ciao,
Dscho

[Grant Harris]

JavaDoc is for source code/API documention.  For general help and
documentation functionality there is the JavaHelp System:
(http://java.sun.com/javase/technologies/desktop/javahelp/)
Any thoughts on using this approach?
- Grant

[Adrian Daerr-2]

Thanks for all ideas on ways of shipping documentation with plug-ins
and accessing it. There are clearly trade-offs; let me try to
summarize what has been said on alternatives to a suggested custom
interface:

* Wilhelm Burger suggested using javadoc comments (which allows adding
   free-form documentation (e.g. usage info, examples) at the top of
   the source-file).
Advantages:
- standard way of documenting java source, with tags etc
- makes sense to have usage+API documentation in same place, because
   many ImageJ users are also 'developers' (they invoke plug-ins from
   the menu as well as from macros/other plug-ins)
- avoids duplicate comments/documentation (java source comments vs
   returning a String through a method);
- existing tools to generate HTML, PDF, from javadoc, implying a
   comfortable browsing experience for the user.
Disadvantages:
- needs source (positive side to it: will encourage open source)
- not easy to extract specific info (except maybe @author, @version
   tags, but has to be done manually), only all-in-one.

* Paul Johnston proposed a centrally hosted plugin registry and a
   package-manager, with submission template requiring documentation
Advantages:
- solves other short-comings of current plug-in-anarchy in the same
move
Disadvantages:
- as Johannes Schindelin underlined (I concur), if there is to much of
   a burden to share a plug-in, developers won't bother sharing.
- a lot of work to create the infrastructure (but cf Fiji)

* Grant Harris pointed to the JavaHelp software as an alternative to
   javadoc. I only very briefly inspected its documentation, so the
   following is maybe false and/or incomplete:
Advantages:
- any HTML-producing editor can be used to write doc.
Disadvantages:
- seems to involve a bit of additional work on plug-in developer to
   format help pages for display by this system (minimum: four
   meta-data files to edit, from what I understand). As pointed out
   above, this might be fatal to the willingness of developers.
- plug-in author has to understand how to build this meta-data. This
   is prohibitive in my opinion. Unless the operation is trivial and
   well documented, or ImageJ generates the meta-data on the fly.

I like Wilhelm Burger's idea very much, and I just learned that
javadoc can be called from within a Java environment:

http://java.sun.com/j2se/javadoc/faq/index.html#runfromwithin

It would be a pity not to move on now that a lot of ideas came up for
the problem at hand. Here is my suggestion version 2: why not offer
the plug-in author a number of alternatives, and provide some standard
access methods ? A balance where we would avoid being to restrictive
on the author, and yet keep a good chance that ImageJ can present some
documentation:

* let the author adopt any one of the following ways to document a
plugin:
- write java-doc comments, with general usage info and example
up-front;
- implement the PluginDoc interface I suggested earlier, which returns
   the doc as tagged fields. A number of these would be mandatory to
   guarantee key information;
- write entirely free-form doc in any format (e.g. HTML, PDF, text or
   RTF), and (optionnally?) implement an interface (I'd suggest using
PlugInDoc here as well, but can be another 'PlugInExternalDoc'
interface) yielding an URL to
   this doc.

* ImageJ (the GUI) offers to show help for a plug-in if either
- the Java source is present, and javadoc can be generated from it;
- the plug-in implements the PluginDoc interface;
- an URL to an external document can be obtained (either through a
   specific interface, or by searching for a file
   The_Plug_In/index.html, The_Plug_In.pdf, or something of the sort
at
   the place where The_Plug_In.class is).

* ImageJ (the API) offers some static methods in the class IJ
(IJ.getPluginAuthor(...) etc) that hide from the user the exact
way in which the info is obtained. That way the PluginDoc interface
stays simple, and other ways of documenting plug-ins may later be
added.


Here is the revised PlugInDoc interface which I would like to propose
to Wayne for inclusion:
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html

the source code is here (for completeness, nothing new here really):
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.java


Do you have more comments on this ? Or suggestions for other keys
which should be mandatory ? Ideas what static IJ.get... methods for
documentation there should be ?

[Michael Schmid]

Hi Adrian,

sorry, I still do not see so much advantage of this over the current  
showAbout() method.
One could encourage users to write part of the showAbout in a  
standardized way (author, license, revision date), but normally there  
won't be any need to extract these from a program, so any format will  
do.
Clickable URLs would be nice, I agree; being able to copy URLs from  
the showAbout windows would be sufficient. The downside: The URL can  
easily change if the author's institution rearranges the web site or  
the author leaves the institution...

A significant progress would be PDFs/HTMLs+images embedded in a .jar,  
but I fear that only few plugin authors will do that. Also, I am not  
sure whether large .jar files would increase the ImageJ startup time.

A repository for plugins is a different thing - this would be really  
nice!
Then, it would make more sense to have a clickable URL, to have a  
revision date that so one could check for updates, etc.

Just my 3 cents.

Michael
________________________________________________________________

On 24 Apr 2009, at 15:27, Adrian Daerr wrote:

> Thanks for all ideas on ways of shipping documentation with plug-ins
> and accessing it. There are clearly trade-offs; let me try to
> summarize what has been said on alternatives to a suggested custom
> interface:
>
> * Wilhelm Burger suggested using javadoc comments (which allows adding
>   free-form documentation (e.g. usage info, examples) at the top of
>   the source-file).
> Advantages:
> - standard way of documenting java source, with tags etc
> - makes sense to have usage+API documentation in same place, because
>   many ImageJ users are also 'developers' (they invoke plug-ins from
>   the menu as well as from macros/other plug-ins)
> - avoids duplicate comments/documentation (java source comments vs
>   returning a String through a method);
> - existing tools to generate HTML, PDF, from javadoc, implying a
>   comfortable browsing experience for the user.
> Disadvantages:
> - needs source (positive side to it: will encourage open source)
> - not easy to extract specific info (except maybe @author, @version
>   tags, but has to be done manually), only all-in-one.
>
> * Paul Johnston proposed a centrally hosted plugin registry and a
>   package-manager, with submission template requiring documentation
> Advantages:
> - solves other short-comings of current plug-in-anarchy in the same  
> move
> Disadvantages:
> - as Johannes Schindelin underlined (I concur), if there is to much of
>   a burden to share a plug-in, developers won't bother sharing.
> - a lot of work to create the infrastructure (but cf Fiji)
>
> * Grant Harris pointed to the JavaHelp software as an alternative to
>   javadoc. I only very briefly inspected its documentation, so the
>   following is maybe false and/or incomplete:
> Advantages:
> - any HTML-producing editor can be used to write doc.
> Disadvantages:
> - seems to involve a bit of additional work on plug-in developer to
>   format help pages for display by this system (minimum: four
>   meta-data files to edit, from what I understand). As pointed out
>   above, this might be fatal to the willingness of developers.
> - plug-in author has to understand how to build this meta-data. This
>   is prohibitive in my opinion. Unless the operation is trivial and
>   well documented, or ImageJ generates the meta-data on the fly.
>
> I like Wilhelm Burger's idea very much, and I just learned that
> javadoc can be called from within a Java environment:
>
> http://java.sun.com/j2se/javadoc/faq/index.html#runfromwithin
>
> It would be a pity not to move on now that a lot of ideas came up for
> the problem at hand. Here is my suggestion version 2: why not offer
> the plug-in author a number of alternatives, and provide some standard
> access methods ? A balance where we would avoid being to restrictive
> on the author, and yet keep a good chance that ImageJ can present some
> documentation:
>
> * let the author adopt any one of the following ways to document a  
> plugin:
> - write java-doc comments, with general usage info and example up-
> front;
> - implement the PluginDoc interface I suggested earlier, which returns
>   the doc as tagged fields. A number of these would be mandatory to
>   guarantee key information;
> - write entirely free-form doc in any format (e.g. HTML, PDF, text or
>   RTF), and (optionnally?) implement an interface (I'd suggest  
> using PlugInDoc here as well, but can be another  
> 'PlugInExternalDoc' interface) yielding an URL to
>   this doc.
>
> * ImageJ (the GUI) offers to show help for a plug-in if either
> - the Java source is present, and javadoc can be generated from it;
> - the plug-in implements the PluginDoc interface;
> - an URL to an external document can be obtained (either through a
>   specific interface, or by searching for a file
>   The_Plug_In/index.html, The_Plug_In.pdf, or something of the sort at
>   the place where The_Plug_In.class is).
>
> * ImageJ (the API) offers some static methods in the class IJ
> (IJ.getPluginAuthor(...) etc) that hide from the user the exact
> way in which the info is obtained. That way the PluginDoc interface
> stays simple, and other ways of documenting plug-ins may later be  
> added.
>
>
> Here is the revised PlugInDoc interface which I would like to propose
> to Wayne for inclusion:
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.html
>
> the source code is here (for completeness, nothing new here really):
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/ 
> PlugInDoc.java
>
>
> Do you have more comments on this ? Or suggestions for other keys
> which should be mandatory ? Ideas what static IJ.get... methods for
> documentation there should be ?

[Adrian Daerr-2]

Hello Michael,

you wrote:
> sorry, I still do not see so much advantage of this over the current
> showAbout() method.
> One could encourage users to write part of the showAbout in a
> standardized way (author, license, revision date), but normally
>there  won't be any need to extract these from a program, so any
>format will  do.

I am not pretending the advantage is huge. There are a number of
small improvements though, for the prize of three lines of code added
to ImageJ (the interface declaration is really tiny):

- an interface declaration (implements ...) makes it easier to know if
a class exposes documentation (you can check with
'if (plugin instanceof PlugInDoc)' instead of using reflection
methods (see the 10 or so lines of code of the installAbout method
in http://rsbweb.nih.gov/ij/source/ij/plugin/Installer.java )
This could of course be done keeping the showAbout method, simply by
declaring an interface PlugInAbout { static void showAbout() }. But
while we're at it, maybe the interface could be better, allowing for a
more flexible way of exposing documentation.

- You might want to collect/expose/process the documentation, or just
display it through a common interface, instead of leaving it to every
plug-in to display its own way inside the showAbout() method. What if
you run head-less for example and showAbout tries to open a Dialog ?

- one small piece of information that users might want to have
explicitly is the release date: just as you can check you are running
on a sufficiently recent ImageJ version, it could be nice to be able
to check that the plug-in you intend to call is also sufficiently
recent.

- being able to include URLs in a way that a plug-in can make
clickable is nice, as you say. Have you tried the Get_help_for_plugin
plugin I originally submitted ? -- really easy to do !
Also note that an URL can point to local resources (PDF or HTML+images
or ...), so this is a very nice way of opening up more convenient ways
of writing documentation (than concatenating strings, limited to pure
text).

The interface itself remains very lightweight (one method, lighter as
the showAbout method because displaying the info is left to the
caller, e.g. the ImageJ GUI), so it seems like worthwile improvements
to me.

Johannes Schindelin commented that specific functions (such as
getReleaseDate()) could be more usefull. I concur, but suggest that
such methods be included in the ij.IJ class. The main advantage with
respect to including them in the interface is that new functions can
easily be added later (while you cannot alter an interface once you
have published it). Other small advantages include the fact that the
plug-in writer still has only one method to implement instead of a
whole series, and the possibility of refering to the plug-in by name
(leaving it to the code under the hood of IJ to load the class):
IJ.getPlugInReleaseDate(String plugin).

thanks for the comments,
regards,
Adrian

[Prodanov Dimiter]

It will be nice if Wayne reaches understanding about the importance of help/documentation.

I see some glitches in the presented idea. In all my years with ImageJ I haven't used showAbout. Because there is no way to get interactive help from a plugin and showAbout does not substitute for it.

What we absolutely need is a consistent help/doc pattern. The format is not so important at the moment.

Obviously there can be place for some diversity like TXT/JAVADOC/HTML or PDF/PS.

If the resources are stored somewhere in the IJ folder tree that can be easy. Another idea is to place them in the src_jar or make a special doc_jar.

So If we insist on developing such a system then an interface coupled with some standard handling methods on the level of IJ will be fine.

Best regards,

Dimiter

[Prodanov Dimiter]

* Paul Johnston proposed a centrally hosted plugin registry and a

package-manager, with submission template requiring documentation

Advantages:

- solves other short-comings of current plug-in-anarchy in the same move

Disadvantages:

- as Johannes Schindelin underlined (I concur), if there is to much of

a burden to share a plug-in, developers won't bother sharing.

- a lot of work to create the infrastructure (but cf Fiji)

----------------

I strongly advocate for such an approach. The infrastructire is already here.
I have developed a web-service enabling framework for ImageJ.
I tried is with Fiji and it works out of the box.
You can see my presentation/paper at the last IJ Conference.

Cheers

Dimiter