Protocols Plug-in FAQ
Table of Contents:
In the event that you are unable to find the information you are looking for amongst the answers below, all is by no means lost. You can either drop me a mail at se.bergner@bergner.se, which I will answer at my earliest convenience; or, if you are truly desperate and have not done so already: search the article.
General questions about the Protocols plug-in
Q: What does the Protocols plug-in do?
A: It supports the wide-spread way of arranging elements of the source code
in sections under separate headers represented by more or less magnanimous
comments. For instants, you may have one section for constructors and
methods for initial things, one for getter and setters, and a third for more
complex stuff, etc. All types of elements: fields, methods, inner types, and
initializes, are handled.
Q: How is this support manifested?
A: The current version applies mostly to the Java Browser perspective
as it specifically connects with the Members View. Its most obvious
feature is a new view that lists the headers, the Protocols View,
intended to sit to the left of the Members View. It also adds a couple
of context menu items to the Types View, Members View, and Java Text
Editor.
Q: Who can use it?
A: Given that this type of source code organization is desired, the plug-in
is useful to programmers who do structural editing via the browser views as
well as to those who do all their editing with the text editor. Capabilities
include outlining, editing, and sorting; by means of context menu commands,
global cut-copy-paste, and drag & drop.
Q: "Headers" seems to relate to documentation, how is Javadoc supported?
A: Surprising as it may seem, Javadoc is not addressed at all. The emphasis
in Protocols is on ease of writing and reading the source code. To my mind,
document preparation with Javadoc is an altogether different story. A
preprocessor for Javadoc generation from source code structured with header
comments would be a useful tool, regardless of if the Protocols plug-in was
used in the creation of the source or not. If this answer was not what you
wanted to hear, check out the "xdoc" plug-in by Chris Grindstaff which takes
on a much more Javadoc centric approach.
Q: Will this plug-in help me to read code written by people who are not
using it?
A: No. This is an authoring tool with which you add information to java
source files by structuring them in an eye catching manner. You have to
contribute the structure and there is nothing subtle about the way it is
manifested in the source code.
Q: What is imposed on my code beyond the general idea of headers?
A: Very little. (See the next two questions.)
Q: Can I control the appearance of the headers?
A: Within reasonable limits, yes. This is one customization amongst several
others offered in two full pages worth of preference settings.
Q: What's with the arcane name dude?
A: The name Protocols comes from Smalltalk-80, out of which Java lends
concepts like object oriented programming, virtual machine, JIT compilation,
etc., etc., including---although perhaps a comparatively smaller
issue---"protocols" for organizing the content of a class. If you don't like
the name, please try to ignore it. I just felt it wasn't mine to change.
Questions about using the Protocols plug-in
Q: Why doesn't selecting protocols in the Protocols view have any affect on
what is displayed in the Members view?
A: The Protocols View is connected to the Members View by the filter
mechanism. If selecting protocols in the Protocols view has no affect on
what is displayed in the Members view, you need to activate the filter
called "Protocols view selection" in the Members view. This is done through
the dropdown menu in the Members view. Once "Protocols view selection" is
check marked, everything will work.
Q: Why does an extra header, called "--X-X--", appear last in the file?
A: This is a record of the header format used in the file, disguised as a
"The End" type of comment. Through it, the header format used in a
particular can be read out of that file. Then when it is scanned for
headers, that format will assumed rather than the default format specified
in the Preference settings. This makes changes to the format (over time,
place, user, and taste) possible to handle.
Q: Why is there an item at the top of the Protocols View that does not
correspond to any of my headers?
A: This is known as the Default Protocol and the name that denotes it in the
view is a preference setting. It is a virtual protocol existing only in the
Protocols View, containing all members that have not been allocated to any
real protocol. In the source there is no header for this Protocol, its
members simply precede the first header. So in a file without headers, all
members belong to the Default Protocol.
Q: Will the headers, and thus my protocols, always survive refactoring
operations?
A: Most of the time, but not always. The problem is that the internal Java
file representation in Eclipse currently will assign all comments to one or
the other Java element (e.g. a method), and whatever happens to an element
will happen to the assigned comments as well. So for instance, if the method
appearing immediately under a header is drag and dropped into another class,
chances are the header will go with it. Yet the header may be assigned to
the element preceding it, in which case nothing bad will happen unless that
element is copied, moved or deleted.