|Timestamp||Which area of the documentation currently not covered would you like us to work on?||Please provide one or more URLs of the existing documentation that really need improvements||Request Name||Your Name||Your email||Person in charge||Form of projected solution||Resolution status|
|6/24/2014 9:52:56||Definition of exactly what is an EiffelStudio project. For example, the Guided Tour uses a sample project which is not much beyond a hello-world program. There is no example (that I've found) of *creating* a realistic project. I also didn't find a clear distinction between what is a project, a system and an application, or whether they're to be treated as synonyms. In my experience a system/project is a group of more than one application programs. Note: I sent a note regarding this confusion on 22/6 via https://docs.eiffel.com/contact.||https://docs.eiffel.com/book/eiffelstudio/eiffelstudio-creating-new-project|
The above doesn't have a screenshot or explanation of the "Choose Your Project Name and Directory" which I think are essential to creating/structuring a project from scratch. I couldn't find a description of this either under https://docs.eiffel.com/book/eiffelstudio/eiffelstudio-reference
|PROJ||Joe Abbate||Alexander Kogtenkov||YouTube video|
|6/24/2014 10:04:40||The first two pages below are marked "Under construction: see definition." This of course requires consulting ECMA-367. In addition, the third page could be improved. For example, it appears that "Location" has to be a full path, rather than a relative one such as "../lib/libsomelib.a". And it would help to explain where to look for things when an external compilation or linking step go awry.||https://docs.eiffel.com/book/solutions/eiffel-external-mechanism|
|6/25/2014 17:57:21||Add documentation in Spanish. I can help on this, translating the most important articles. Make some videos, less technical and more demonstratives. The people need see quickly what can do with EiffelStudio, specially the beginner programmers. I also can help on this, although my English isn't perfect. Also, is necessary a page with the pebbles descriptions. I don't understand what mean some pebbles I see on EiffelStudio.||https://docs.eiffel.com/ needs a link to EiffelBuild.||Germán Arias|
|6/27/2014 3:37:27||Agents, as covered in docs.eiffel.com. (I always look there first whenever I need help with Eiffel.) Recently I was looking for an explanation of how agents with an open target (and possibly open arguments) are invoked (called). I couldn't find an example on docs.eiffel.com, but did at http://se.inf.ethz.ch/~meyer/publications/joop/agent.pdf, in the section labeled "Keeping arguments open." Adding the examples from the pdf document to docs.eiffel.com would have helped me.||https://docs.eiffel.com/book/method/et-agents (It's good,but could use some more examples for how agents with open arguments are declared and called.)||David Jenkins|
|6/29/2014 16:54:20||The Command line arguments example solution does not fulfill the contract given by Rosetta Code, i.e., retrieve the list of command-line arguments and (implicit in virtually all the other solutions), print each argument. Instead the solution attempts to deal only with the options and arguments given as an example in the spec. The program would fail to print anything if invoked with any other arguments. Note: separate email sent.||https://docs.eiffel.com/book/examples/example-command-line-arguments||Joe Abbate|
|7/3/2014 7:04:29||Add documentation about exceptions as objects and make obsolete the documentation of the old mechanism (EXCEPTIONS with code and strings).||http://www.eiffelroom.org/blog/ted_eiffel/take_advantage_of_eiffel_exceptions_as_objects|
|7/3/2014 11:15:27||The current text at the URL below only states that "note" is involved in class headers and check instructions. However, from the "void safety" page, it is also used to define stable attributes.||https://docs.eiffel.com/book/method/eiffel-programming-language-reserved-words#note||Uses of the "note" firstname.lastname@example.org||Victorien Elvinger||Enable notes in a feature declaration - Indeed note cluases are allowed on both attributes and routines.||Done|
|7/3/2014 14:50:47||The description of self-initializing attributes at the URL below states that such attributes are "characterised by the attribute keyword". Not quite so since, further down the page, stable attributes are shown as being declared with this same keyword (without a body).||https://docs.eiffel.com/book/method/void-safety-background-definition-and-tools#Self-initializing_attributes||Uses of the "atribute" email@example.com||Alexander Kogtenkov||Fix the description||Done|
|7/6/2014 10:53:45||The parenthesized alias for features is not documented. It looks like the Bracket construct in the below section of the syntax page should read|
Bracket ::= "[ ]" | "( )"
More generally, other features mentioned at https://docs.eiffel.com/sites/docs.eiffel.com/files/expression_language_0.pdf do not seem to be documented either, requiring the update of more items in the Syntax, Tutorial and Other mechanisms pages.
|https://docs.eiffel.com/book/method/eiffel-programming-language-syntax#Feature_names||Include most recent firstname.lastname@example.org||Bertrand Meyer|
|7/6/2014 11:13:06||The "name" field has the following label: "... easy to identify the <b>request</b> ...". From the spreadsheet for EDD, those who made a request used their own names. Two interpretations then:|
1/ The requester (nick)name is required for individual email exchange for the purpose of clarification. Then what happens for requesters with several entries?
2/ A request name is preferred. Then, how will the author be contacted for clarification? Using the Yahoo list I guess.
|7/7/2014 5:26:48||ECMA-367 declares an optional "convert" mark as liable to be added to aliases - so does the syntax for Feature_names accordingly. However, the way it works is unclear, and a precise statement of what it does and what it needs to work (a convert clause somewhere?) is probably useful.||https://docs.eiffel.com/book/method/et-other-mechanisms#Convertibility||Convert mark for email@example.com|
|7/9/2014 7:25:48||Currently, we can only find the ability to apply key accelerators with matching underlined characters in the text of the EV_WIDGET on EV_MENU_ITEM objects by way of an injected & character on the `text' of the control.|
We have confirmed that Windows controls such as buttons do have "Access Keys" (see http://msdn.microsoft.com/en-us/library/aa983581(v=vs.71).aspx). We are not sure about Linux or other platforms, which may be the source of the limitation.
In any case, we think Access Keys (accelerator keys) on buttons is a common enough expectation that it deserves to be well documented. Further, we expect this documentation to be contained in the class notes clause itself (see EV_MENU_ITEM note description for an example). If the EV_BUTTON has a platform limit and the Access Keys have been left-off due to these limits, then the EV_BUTTON class needs to state this clearly as NOT having it breaks the common expectation.
NOTE: Regarding the self-documentation principle: What a class does not have (for whatever reason) cannot be self-documented except by way of a note clause entry on either the class or the feature(s) it impacts. In other words, features missing or purposefully excluded for whatever reason need to be noted by the DESIGNER and CODER of the class, especially if the consumer community at-large has an expectation that is not met for some reason.
NOTE: https://docs.eiffel.com/static/libraries/vision2/ev_button_chart.html <-- just about worthless without orientation documentation material for the novice learner and even returning reader who needs a deeper refreshing. We can get this in Eiffel Studio without having it docs.eiffel.com. Do not include things as "documentation" that are not really documentation at all, but just calculated artifacts that can be had easily and handily from the IDE.
The `accelerators' example from:
1. Failed to compile, but that may be due to our project Env Var settings and I am unwilling to upset that apple-cart at the moment.
2. I created another accelerator project of my own -- rinse and repeat. However, in this case, I am going to not just do a single example of an accelerator (Access Key) on a window, where the caption of the window (not a common use case) states what the accelerator key is (e.g. "Let's be real, please!").
I do not have time (presently) to follow through, but so far my own accelerator example works, but not fully. The Control+Q is not responding to close the window. Moreover, I attempted to add an EV_BUTTON, but an accelerator on it, but have not made that work yet. So, for the moment (because I have other project work that is more pressing) I am going to abandon this matter and feel I have taken it as far as I can. I will try to pick the matter up later on my own time and see how far I can get. The goal will be to learn (even if the hard way) and provide the necessary IN-CLASS documentation for the appropriate class note clauses.
|7/10/2014 6:55:49||EV_FIGURE and descendants.|
1. The documentation found in the noted docs.eiffel.com article below, can be readily placed in the EV_FIGURE class (at some level). For example:
title : "Graphical Figure"
description : "[Representation of graphically projectible objects.]"
brief : "[
The EiffelVision 2 figure cluster providesa high-level way of drawing on an EV_DRAWABLE descendant.
It offers a number of advantages:
The model (tree of figures) is separated from the graphical representation by using projectors that
take a "world" (an entire set of figures) and project it onto any device, not just a drawing area.
purpose : "[
Drawing with objects solves the problem of managing rotation, scaling, and location, which is
difficult to do with only static APIs like draw_line.
how : "[
Instead of drawing with static APIs like draw_line, you can use real figure objects, which internally
remember their location, rotation and scaling; later on you can perform limitless transformations on
them, either individually or as part of an entire branch in the tree of figures: move, rotation,
scaling, change of color, and so on.
For projection devices that support the mouse, pointer events propagate to the affected figures.
usage : "[
Every basic figure class inherits from EV_ATOMIC_FIGURE. An atomic figure has the property of
having its own graphical representation. EV_FIGURE_GROUP on the other hand is a collection of
figures. Finally, EV_FIGURE is the common ancestor to those two. Since EV_FIGURE_GROUP is a
collection of EV_FIGUREs, it can contain both atomic figures and subgroups, thus forming a
tree of figures.
Any "branch" of that tree that wishes to be drawn (i.e. rendered to a device or file) (especially
the top-level root) must be a figure group of type EV_FIGURE_WORLD. It inherits from EV_FIGURE_GROUP,
and adds some features for grid and background color, required for drawing.
Class Open/Closed Points Description
EV_FIGURE_ARC open 2 a segment of an open ellipse
EV_FIGURE_DOT open 1 a single point
EV_FIGURE_ELLIPSE closed 2 an ellipse inside imaginary rectangle
EV_FIGURE_EQUILATERAL closed 2 a figure with any number of sides of the same length
EV_FIGURE_LINE open 2 a straight line between two points
EV_FIGURE_PICTURE open 1 an image positioned by its top-left point
EV_FIGURE_PIE_SLICE closed 2 a part of a closed ellipse
EV_FIGURE_POLYGON closed * a figure defined by any number of points
EV_FIGURE_POLYLINE open * a figure consisting of any number of connecting lines
EV_FIGURE_RECTANGLE closed 2 a figure with four sides
EV_FIGURE_STAR open 2 any number of lines emerging from a center point
EV_FIGURE_TEXT open 1 a string positioned by its top-left point displayed in the specified font
A closed figure is a figure that has some area enclosed when drawn that can optionally be filled with a color. Closed figures inherit EV_CLOSED_FIGURE which gives them the property fill_color. Open figures inherit EV_ATOMIC_FIGURE directly, as does EV_CLOSED_FIGURE.
BNF : "[
See descendents of EV_FIGURE.
glossary : "[
projector: Any device capable of having a world of figures drawn upon it (e.g. screen, printer, plotter, others)
figure tree: A tree of figures, where figures are the nodes and worlds and sub-worlds are the containing branches.
examples : "[(optional) <code_examples_when_non_trivial_or_especially_illustrative>]"
see_also : "[
See the EIS links below for external documentation.
EIS: "name=Eiffel Docs Figures", "protocol=URI", "src=https://docs.eiffel.com/book/solutions/figures"
NOTE: This format may now descend down into the descendant classes, where further orienting documentation can reveal to the user how to use the specific figures within their worlds.
|https://docs.eiffel.com/book/solutions/figures||Larry Rix||Larry Rix|
|7/10/2014 10:34:53||EV_FIGURE, specifically EV_FIGURE_WORLD:|
The docs.eiffel.com article talks about:
Rotation and Scaling
Relative Points also support rotation and scaling. Both rotation and scaling can be entered at any point in the tree of relative points. One of the most useful of these points is the point of an EV_FIGURE_GROUP, which rotation and/or scaling will then propagate down the tree to all the contained figures and sub-groups. Rotation is in radians progressing counter-clockwise from the positive X axis. Scaling is multiplied into the chain of relative points. This means that when a relative point which is the root of a tree of several points is moved, the entire tree is moved. When it is scaled the entire tree is scaled, and the same for rotation.
The scaling factor has two components: horizontal (x) and vertical (y), which can be set separately or together. If the x/y scaling factor is 0.5, everything at that point and below in the tree is displayed at half its normal size.
In that description it talks about rotation and scaling, but there are no features by any such name. There are no obvious features that seem to control except maybe for orientation, which has no setter and apparently does not respond to my_world.orientation.set_item (n) at all. If it is a matter of "you are not using it right" <-- NOT GOOD ENOUGH ANSWER! Of course I am NOT using it right! I have no documentation! I have no orientation!
|7/10/2014 20:53:35||Examples in the use of class EXCEPTIONS and solve the problem with some links of this class in documentation. In some pages this class link to the correct documentation. But in others link to a search in Google, and this isn't expected.||For example in this page are wrong links to EXCEPTIONS class:|
|7/16/2014 23:27:43||English isn't my mother language but in "Hello World" page, I think "however ambitious its goals" should be "no matter its ambitious goals" (first paragraph).||https://docs.eiffel.com/book/method/et-hello-world||Germán Arias|
|7/18/2014 3:06:26||Documentation of the drawing tool /BON. I have tried it several times and it works but I never get any structure of it and can never find old diagrams that I have done. Might be realted to that one delete the EIFGEN folder sometimes. |
It would be nice with a step by step guide.
I Think I wrote an error report many years ago. (I found it 16954)
I can help by testing the documentation and see if I understand it.
|7/21/2014 2:16:27||The documentation for EiffelWeb states "You may then send the header followed by your text using the features send_to_browser of classes CGI_RESPONSE_HEADER and HTML_PAGE. " But HTML_PAGE does not have the send_to_browser command. Since returning a web page is a common activity, the proper way to do it should be clearly explained.||https://docs.eiffel.com/book/solutions/processing-requests||EiffelWeb - send firstname.lastname@example.org|
|7/24/2014 1:38:48||There is ample justification in void safety specifics being covered in a separate document. However, and specially for those who start projects from scratch, having several sources to look at may be awkward. Same goes for the "Other mechanisms" page: spinning the Agents chapter off was a step in the right direction, to be followed by more.|
Proposal: add to main tutorial new pages corresponding to contents of the void safe page or other mechanisms pages. Specifically, the new following items would appear:
* Constants (OM 1 & 2)
* Creation (OM 4, VS 2.9, DSEM 4)
* ET: Inheritance -> Inheritance and conformance (OM 6, VS 1.1, 2.3 & 2.6). Or have a specific new Conformance section in DSEM - after all this concept has been the core of the type system.
* Tuples (OM 7)
* Add initialisation related matters into DSEM 4: VS 2.4 2.5 2.7
* Add VS 2.8 to ET Genericity and arrays
* Add VS 2.2 to ET: Instructions
* Add OM 5 to DSEM 6
* New ET: Code base management page, to cover OM 3 and the various uses of /notes/ keyword.
* Perhaps a new "Old syntax" page with everything that had been in eiffel at some point but no longer are, and how to convert such constructs (?=, strip, unique, !! and friends)
* Perhaps a new "Avoid Void" section in DSEM to cover VS 1 & 2.1
Duplicating the material is not necessary: the new pages or sections could have terse content and link to existing pages for details.
DSEM is a pretty long page which may need trimming now, or splitting up rather. Breakup suggestion: Objects (1 4 5), Features (2 3 15), Calls (6 7 10 13 14), Types (8 9), Memory and Storage (11 12). Some of the smaller pieces may deserve being gathered back.
|8/4/2014 1:27:06||Sections 1.4 and 2.1 of the refrenced page list issues arising from SCOOP being partially suported in EiffelStudio. These notes appear to date back from version 6.8, released a few years ago. The page should mention whether the limitations still hold in current version, and when and how they were relaxed, as applicable.||https://docs.eiffel.com/book/solutions/scoop-implementation||/separate/ email@example.com|
|8/7/2014 14:12:12||The chart showing when the various values of a preference are used is based on something called "my preference". Yet, a couple lines below, the page reads: "Using the example preference above, window_width_preference, you can query..." So the chart above should refer to window_width_preference instead.||https://docs.eiffel.com/book/solutions/initialization||Example preferences - small firstname.lastname@example.org|
|8/31/2014 16:35:00||In the void-safety tutorial, there is a set of recipes using the "attached" syntax. Among them, an obsolete code pattern using it to adjust the semantics of once features. The "once key" link there is obsolete (points to Other mechanisms) and should be https://docs.eiffel.com/book/method/et-once-routines-and-shared-objects#Adjusting_once_semantics_with_.22once_keys.22.|
|https://docs.eiffel.com/book/method/creating-new-void-safe-project#More_about_the_attached_syntax||once per object email@example.com||Victorien Elvinger||Fix the reference||Done|
|10/6/2014 15:06:58||The Eiffel Graph library is not learnable. There is no indication given anywhere in the library or class texts about where to start, overview of the library, and so on. There is one small snippet in EG_GRAPH stating that it wants to be used within an EG_FIGURE_WORLD.|
From the code it is impossible to tell what the design intent was, the intended purpose, how it accomplishes the purpose, examples, glossary of terms, and so on. There are no clues as to what classes to start with, how to build simple graphs (if that is what the library is even for).
This is a prime example of a NIH library where I have spent an afternoon looking and trying to understand and come away with a dry hole experience and am very angry that I cannot learn this library because I have nothing learnable reachable by me.
|There are no documents that I can find in docs.eiffel.com—none at all.||Eiffel Graph||Larry Rixfirstname.lastname@example.org|
|1/18/2015 9:15:36||The diagram of TWO_WAY_LIST, at the end of section 4.2 "Linked Structures" uses instances of LINKABLE as cells, instead of instances of BI_LINKABLE, and it doesn't show the reverse arrows from each instance to the previous one.||https://docs.eiffel.com/book/solutions/eiffelbase-data-structures-lists||Diagram of TWO_WAY_LIST||Joe Abbateemail@example.com|
|2/1/2015 21:21:44||The fundamental stack operations (put, item, remove and is_empty) all use queue terminology, e.g.,|
put (add an element at end of queue)
put (push an element onto top of stack)
|https://docs.eiffel.com/book/solutions/eiffelbase-dispensers||Stack ops described as queue ops||Joe Abbatefirstname.lastname@example.org|