search

xjiang4 / ellipsoids

Automatically exported from code.google.com/p/ellipsoids
Other
0 stars 1 forks source link

Update ET documentation to account for the latest changes the toolboox #81

Open GoogleCodeExporter opened 8 years ago

GoogleCodeExporter commented 8 years ago 
The current documentation is out of date, more specifically

1) Legacy object-oriented technique used in ET 1.1.3 was replaced with the new 
OOP implemented in newer versions of Matlab. This allows for calling a method 
myMethod of object obj like obj.myMethod(...) while the legacy technique 
allowed only for myMethod(obj,...) form. Thus we need to adjust the examples to 
encourage users to use the new syntax.

2) Format of some methods in ellipsoid/hyperplane classes was changed, we need 
to make sure that the documentation is up to date. Also, some of the methods 
now support multi-dimensional arrays. Finally, some new methods may have been 
added. 

3) reach, linsys classes have been replaced by elltool.reach.ReachContinuous, 
elltool.reach.ReachDiscrete and elltool.linsys.LinSys classes with a 
slightly-changed format of input parameters in the constructor and some of the 
methods. 

4) Algorithms of S matrix calculation for internal approximation have been 
changed.

5) The new quadratic regularization technique has been implemented for the 
systems with uncertainty.

Original issue reported on code.google.com by heartofm...@gmail.com on 22 Mar 2013 at 5:57

GoogleCodeExporter commented 8 years ago 
The main problem with reach/linsys/hyperplane/ellipsoid sections is the way 
these objects are described: "these objects have fields:...". But all this had 
to do with old toolbox, in the new version there are no public fields anymore, 
everything is changed via methods. Thus we need to redesign these sections a 
bit:

1) Make the sections more user-friendly and less programmatically oriented. For 
developers we have examples and the appendix. These sections are not for 
developers. Thus I would suggest to

a) change section names: reach -> Reachability set, ellipsoid->Ellipsoid etc. 
b) explain what these objects do in plain words as opposed to listing their 
properties (which we do not have any more, at least public ones so for a user 
they do not exist). For ellipsoid we need to say that each object represents a 
single ellipsoid, that we can construct arrays of ellipsoid and perform the 
following mathematical operations and then list those operations not as 
functions but in plain words.  Same for hyperplane. For reachability domains we 
need to say that that the object represents a reachability domain that can be 
projected, evolved (see evolve method), cut (see cut method). Also we can check 
an intersection of reachability domain with certain objects etc. Same for 
linsys - no listing the properties which we do not have, just in plain words 
what the object does. 

Please note that to make such a description for each object you need to 
understand how they work by yourself, only in this case you will be able to 
write a good description. If you have questions about these objects - please 
let me know. 

2) We should not use the old names anywhere (linsys,reach etc). Please scan all 
the document and make sure that these old short names are not use. They should 
be replaced either with new class names or just with plan words like "Linear 
system", "Reachability domain" etc.

3) Section 6.1, enumeration. The parameter names are still incorrect, please 
open xml configuration for comparison (elltool.editconf('default')). 

4) Please change the end date at the front page to 2013, and please specify the 
toolbox version (1.4)

Thanks.

Original comment by heartofm...@gmail.com on 10 Apr 2013 at 8:55

GoogleCodeExporter commented 8 years ago

Original comment by irizk...@gmail.com on 11 Apr 2013 at 2:14

Attachments:

GoogleCodeExporter commented 8 years ago 
1) I think we need to get rid of Chapter 6 and merge its content with chapter 5 
so that

6.1 Properties is moved to a separate section in chapter 5, 6.2 is merged with 
5.1, 6.3 is moved to a separate section in chapter 5 (after ellipsoids), 6.4 
and 6.4 are merged with 5.2.

2) In Properties section please mention the setters (like Properties.setAbsTol) 
that can be used to change the settings one the fly.

Original comment by heartofm...@gmail.com on 11 Apr 2013 at 2:34

GoogleCodeExporter commented 8 years ago 
Please mention LinSysFactory that can also be used for creating LinSys objects.

Original comment by heartofm...@gmail.com on 11 Apr 2013 at 2:39

GoogleCodeExporter commented 8 years ago 
4) Please do not forget to put the toolbox version number (1.4) on the front 
page.

Original comment by heartofm...@gmail.com on 11 Apr 2013 at 2:41

GoogleCodeExporter commented 8 years ago 
2)In current version of the manual there is following text:
... Some of the parameters can be changed in run-time via setters.
and example s_chapter06_section01_snippet03.m
Isn't this enough?

Original comment by irizk...@gmail.com on 11 Apr 2013 at 2:58

GoogleCodeExporter commented 8 years ago 
It would if the example was correct but it doesn't:

lltool.conf.Properties.setIsVerbos = 0; is incorrect for many reasons

1) Misprint, not e at thened
2) setIsVerbose is a method, not a field, you cannot write 
Properties.setIsVerbose=something
3) the method accepts logical values (true or false), not numerical ones.

Also, the values in getters section are also incorrect (numberical values 
instead of logical ones). You need to call every method and put the correct 
sample values

Original comment by heartofm...@gmail.com on 11 Apr 2013 at 4:28

GoogleCodeExporter commented 8 years ago 
Ok, I fixed this.

>> elltool.conf.Properties.getIsVerbose()

ans =

     0

Through this getter we must get logical values, right?
Should I correct something?

Original comment by irizk...@gmail.com on 11 Apr 2013 at 4:58

GoogleCodeExporter commented 8 years ago

Original comment by irizk...@gmail.com on 11 Apr 2013 at 5:40

Attachments:

GoogleCodeExporter commented 8 years ago 
>> class(elltool.conf.Properties.getIsVerbose)

ans =

logical

So it is ok
-------------------------------------------------------
Please concentrate on the help collector now. Thanks.
---------------------------------------------------------------

Original comment by heartofm...@gmail.com on 11 Apr 2013 at 7:42

GoogleCodeExporter commented 8 years ago 
There is one huge problem.
1)If a class inherits from another class,there is a bug
For instance,
emptyObj=eval(['elltool.linsys.ALinSys','.empty(0,0)'])
Error using elltool.linsys.ALinSys.empty
Creating an instance of the Abstract class 'ALinSys' is not allowed.

I corrected your example and now I use this code:
isHandleClass = strcmp(char(mc.SuperclassList.Name),'handle');

2)But the problem did not disappear.
If the class inherits from another class, which inherits from another class, 
which inherits from handle, there are handle methods for the first class in the 
final document.

For instanse, LinSysContinuous->ALinSys->ILinSys->handle.

What should i do?

Original comment by irizk...@gmail.com on 16 Apr 2013 at 10:42

GoogleCodeExporter commented 8 years ago 
If a class is abstract, you should skip it before checking if it is a handle 
class or not. The way to check whether a class is abstract or not is described 
at 
http://www.mathworks.com/matlabcentral/answers/43892-can-i-find-out-if-a-class-i
s-an-abstract-class-before-trying-to-instantiate-it

Original comment by heartofm...@gmail.com on 16 Apr 2013 at 11:06

GoogleCodeExporter commented 8 years ago 
1)What documentation is being changed in the current moment?
2)help('elltool.reach.ReachContinuous.evolve')

  DISPLAY - displays the reach set object.

  Input:
    regular:
        self.

  Output:
    None.

Help for elltool.reach.ReachContinuous/evolve is inherited from superclass 
elltool.reach.IReach

There is the same problem for all methods in elltool.reach.ReachContinuous.
Help for all metdods is shifted.
3)What methods we need for the first version of functions.pdf?
In the current version there are 2000 methods.

Original comment by irizk...@gmail.com on 16 Apr 2013 at 9:18

GoogleCodeExporter commented 8 years ago 
1) Documentation for Reach classes as per issue 85
2) I know about this, once help is deleted from ReachContinuous it will be 
completely inherited from IReach. Artem knows about this. 

If you mean that there is some blank space in front of each line - just delete 
it in your tool. To do it properly you need to calculate this minimum amount of 
blanks among all lines and remove that many blacks from each line. Example:
'  Function'
'     sdfsf'
'    dd    '

should be transformed into
'Function'
'   sdfsf'
'  dd    '

3) All methods of the following classes/packages (excluding test methods)

ellipsoid, 
hyperplane, 
elltool.reach
elltool.linsys
elltool.core.GenEllipsoid
elltool.conf.Properties

Please note that you generate tex file suitable for including into the manual, 
we do not need a separate document.

Original comment by heartofm...@gmail.com on 16 Apr 2013 at 9:46

GoogleCodeExporter commented 8 years ago 
There is the first version of new manual.
1)I should expand ignorList, right?
2)Do we need examples for all methods?
3)Earlier I compiled tex file into the separate document with other packages. 
In this document help headers looked different
I think I have to make help headers wider for elltoolnamual.

Original comment by irizk...@gmail.com on 18 Apr 2013 at 3:07

Attachments:

GoogleCodeExporter commented 8 years ago 
1) Why do you think we need it?

I noticed that you included everything from elltool.conf package... Instead I'd 
suggest to list only elltool.conf.Properties. 

2) Yes 

3) ok

Original comment by heartofm...@gmail.com on 18 Apr 2013 at 3:16

GoogleCodeExporter commented 8 years ago 
1)Which other way I can exclude packages and classes?
Still there is a lot of unnecessary information.

Original comment by irizk...@gmail.com on 18 Apr 2013 at 3:28

GoogleCodeExporter commented 8 years ago 
elltool.doc
elltool.demo
elltool.logging etc..

Original comment by irizk...@gmail.com on 18 Apr 2013 at 3:35

GoogleCodeExporter commented 8 years ago 
Right but where do you get these packages from if on input you only specify

{'ellipsoid','hyperplane','elltool.conf.Properties','elltool.reach','elltool.lin
sys'}?

elltool.doc doesn't belong to the packages listed above so it shouldn't be 
parsed, correct?

Original comment by heartofm...@gmail.com on 18 Apr 2013 at 3:56

GoogleCodeExporter commented 8 years ago 
Oh,so simple.
Thanks.

Original comment by irizk...@gmail.com on 18 Apr 2013 at 4:03

GoogleCodeExporter commented 8 years ago 
I've just committed a modifycopyright function into the trunk. The function is 
designed to scan the folder structure recursively and update the help headers 
with the new copyright information. You might need to adjust it a bit so that 
it doesn't screw up our help headers (theoretically it shouldn't). Also you 
would have to update the map between the login names and full author names on 
line 228 based on email addresses of all students.

Original comment by heartofm...@gmail.com on 18 Apr 2013 at 5:32

GoogleCodeExporter commented 8 years ago 
Should i add new examples in doc\mcodesnippets?

Original comment by irizk...@gmail.com on 18 Apr 2013 at 8:31

Attachments:

GoogleCodeExporter commented 8 years ago 
Please, could you show me an example of a function call
modgen.doc.modifycopiright
All my efforts lead either to 
 INFO modgen.doc.modifycopyright - Could not find place to add Copyright info.
 file: D:\Users\Ira\mybranch\products\elltoolboxcore\@ellipsoid\disp.m

or to

Error using modgen.doc.modifycopyright>modifyfilecopyright (line 175)
failed to process file 
"D:\Users\mybranch\products\elltoolboxcore\@ellipsoid\disp.m"

Error in modgen.doc.modifycopyright (line 29)
    modifyfilecopyright(pathName,fIsStartLine,fIsDelLine);

Original comment by irizk...@gmail.com on 18 Apr 2013 at 10:12

GoogleCodeExporter commented 8 years ago 
I'm not quite sure what is the marker and how it should look.

Original comment by irizk...@gmail.com on 18 Apr 2013 at 10:24

GoogleCodeExporter commented 8 years ago 
1) Here is an example:

1) You open elltool.reach.ReachFactory and put a separate commented line % 
PUTCOPYRIGHTHERE at arbitrary place

2) Then you run modgen.doc.modifycopyright('<YOUR TOOLBOX ROOT 
PATH\products\+elltool\+reach\','PUTCOPYRIGHTHERE')

3) See that the copyright is inserted on the line where PUTCOPYRIGHTHERE was. 

Please do not forget to update the map on line 228 because it needs to contain 
the key-value pairs for each svn user. If you encounter an error like this:

Error using modgen.doc.modifycopyright>modifyfilecopyright (line 174)
failed to process file 
"D:\SVN_Local\EllToolBoxTrunk\products\+elltool\+reach\ReachFactory.m"

Error in modgen.doc.modifycopyright (line 60)
            modifyfilecopyright(fullElemName,fIsStartLine,fIsDelLine);

Caused by:
    Error using modgen.doc.modifycopyright>authorNick2Name (line 239)
    The specified key is not present in this container.
        Nickname kirill.mayantsev@gmail.com not found

this means that you need to add the nickname 'kirill.mayantsev@gmail.com' to 
the map.

2) >Should i add new examples in doc\mcodesnippets? 

All examples from mcodesnippets should be referenced from the manual. So if you 
put it there it should be somewhere in the document. On the other hand, if you 
have the same example in some help header, no need to duplicate but having an 
example in mcode snippets is better than in help header because in the first 
case this example is tested. 

Thus - all complex examples should go into Examples section in the manual (and 
in mcodesnippets). All simple ones should stay in the help headers

Original comment by heartofm...@gmail.com on 19 Apr 2013 at 8:18

GoogleCodeExporter commented 8 years ago 
1)I have a such bug:
Error using modgen.doc.modifycopyright>modifyfilecopyright (line 175)
failed to process file 
"D:\Users\mybranch\products\elltoolboxcore\@ellipsoid\dimension.m"

Error in modgen.doc.modifycopyright (line 29)
    modifyfilecopyright(pathName,fIsStartLine,fIsDelLine);

Error in Untitled (line 1)
modgen.doc.modifycopyright('D:\Users\mybranch\products\elltoolboxcore\@ellipsoid
\dimension.m','PUTCOPYRIGHTHERE')
Caused by:
    Error using modgen.subversion.getrevisionbypath (line 24)
    "svnversion" ­Ґ пў«пҐвбп ў­гв७­Ґ© Ё«Ё ў­Ґи­Ґ©Є®¬ ­¤®©, ЁбЇ®«­пҐ¬®© Їа®Ја ¬¬®© Ё«Ё
    Ї ЄҐв­л¬ д ©«®¬.

2)I'm going to delete all examples s_appendixA_.. from doc\mcodesnippets.
They are very simple.
Ok?

Original comment by irizk...@gmail.com on 19 Apr 2013 at 10:55

GoogleCodeExporter commented 8 years ago 
1) you need to install sliksvn from http://www.sliksvn.com/en/download
2) ok if you already have them in the help headers.

Original comment by heartofm...@gmail.com on 19 Apr 2013 at 10:59

GoogleCodeExporter commented 8 years ago

Original comment by heartofm...@gmail.com on 20 Apr 2013 at 9:09

GoogleCodeExporter commented 8 years ago 
1)About modgen.doc.modifycopyright.
I updated map. 
Should i run this funtion for all directories?
If I should, then i must do svn-checkout from trunk, right?

Original comment by irizk...@gmail.com on 20 Apr 2013 at 10:54

GoogleCodeExporter commented 8 years ago 
No, you shouldn't. I've provided this function so that you can extract the 
author information for the methods/functions which do not have it in the help 
headers. No need to run it for all the toolbox.

Original comment by heartofm...@gmail.com on 20 Apr 2013 at 11:03

GoogleCodeExporter commented 8 years ago 
I don't know what to do with a such type of lines:
Help for elltool.linsys.LinSysContinuous/getAbsTol is inherited from superclass 
ELLTOOL.LINSYS.ALINSYS
etc..

Original comment by irizk...@gmail.com on 20 Apr 2013 at 8:02

GoogleCodeExporter commented 8 years ago

Original comment by irizk...@gmail.com on 20 Apr 2013 at 8:03

Attachments:

GoogleCodeExporter commented 8 years ago 
>Help for elltool.linsys.LinSysContinuous/getAbsTol is inherited from 
superclass >ELLTOOL.LINSYS.ALINSYS
>etc..

This means that this method needs to be documented in the super class. You need 
to  clear the documentation for such methods in elltool.linsys.LinSysContinuous 
and document them in ILinSys

Original comment by heartofm...@gmail.com on 21 Apr 2013 at 9:56

GoogleCodeExporter commented 8 years ago 
Please use todonotes package to put notes in the places which you edited/added. 
This way I'll know what parts of the manual need checking. Also, please keep 
the test pack for this snippets up to date.

Original comment by heartofm...@gmail.com on 21 Apr 2013 at 12:16

GoogleCodeExporter commented 8 years ago 
[deleted comment]
GoogleCodeExporter commented 8 years ago 
Updated help headers in linsys. 
There is the only one problem. Such type of lines(Help for 
elltool.linsys.LinSysContinuous/getAbsTol is inherited from superclass 
>ELLTOOL.LINSYS.ALINSYS) doesn't fit the page.

Original comment by irizk...@gmail.com on 21 Apr 2013 at 12:53

GoogleCodeExporter commented 8 years ago 
I see, then please make the help collector remove such lines automatically.

className='elltool.linsys.LinSysContinuous';
methodName='getAbsTol';
helpStr=help([className,'.',methodName);
indStartDel=strfind(res,sprintf('Help for %s/%s',className,methodName));
helpStr(indStartDel:end)=[];

For todo notes please use 'inline' specifier' i.e. \todo[inline]{dfsfds}, not 
\todo{dsfsdf}. Thanks.

Original comment by heartofm...@gmail.com on 21 Apr 2013 at 12:55

GoogleCodeExporter commented 8 years ago

Original comment by irizk...@gmail.com on 21 Apr 2013 at 12:55

Attachments:

GoogleCodeExporter commented 8 years ago

Original comment by heartofm...@gmail.com on 21 Apr 2013 at 1:34

GoogleCodeExporter commented 8 years ago

Original comment by irizk...@gmail.com on 23 Apr 2013 at 6:33

Attachments:

GoogleCodeExporter commented 8 years ago 
About the todo notes I asked for - I need them mostly for the sections of the 
document you edited excluding the appendix. When looking at the last version I 
haven't noticed any except for the one in the appendix.

Original comment by heartofm...@gmail.com on 23 Apr 2013 at 6:54

GoogleCodeExporter commented 8 years ago 
1)What should I do with ellipsoid.loadobj and 
elltool.linsys.LinSysFactory.create?
2)What is my next step?I'm waiting for Eugene, Vitaly and Ilya, right?

Original comment by irizk...@gmail.com on 26 Apr 2013 at 9:02

Attachments:

GoogleCodeExporter commented 8 years ago 
1)loadobj is already deleted in trunk. As for Factory.create - please document 
it.

2) You need to add the todo notes I asked for - I need them mostly for the 
sections of the document you edited excluding the appendix. When looking at the 
last version I haven't noticed any except for the one in the appendix.

For todo notes please use 'inline' specifier' i.e. \todo[inline]{dfsfds}, not 
\todo{dsfsdf}. Thanks.

3) Function reference section needs to be refined by grouping the classes into 
section. Currently all methods form a single list which is very inconvenient to 
read. Please modify the help collector so that it creates a separate section 
for each class and separate subsection for each method. The goal is to be able 
to navigate through methods via bookmarks in pdf document.

Once you do 1-3 we will wait for Eugene, Vitaly and Ilya.

Original comment by heartofm...@gmail.com on 26 Apr 2013 at 3:01

GoogleCodeExporter commented 8 years ago 
1)Oh, I was sealed. elltool.linsys.LinSysFactory.empty, I meant.

Original comment by irizk...@gmail.com on 26 Apr 2013 at 4:49

GoogleCodeExporter commented 8 years ago 
"empty" methods should be excluded the the final list for all the classes. 
Please just create a list of ignored methods so that we can extend it if 
necessary.

Original comment by heartofm...@gmail.com on 26 Apr 2013 at 5:28

GoogleCodeExporter commented 8 years ago 
Can you please insert a tab (or at least a blank space in Example: sections), 
i.e.

write

Example:
   sdfsdf
   sdfsdf

instead of

Example:
sdfsdf
sdfsfd

Original comment by heartofm...@gmail.com on 26 Apr 2013 at 6:44

GoogleCodeExporter commented 8 years ago 
4) Please include the following classes to the list:

gras.ellapx.smartdb.rels.EllTube,EllTubeProj,EllUnionTube,EllUnionTubeStaticProj

Original comment by heartofm...@gmail.com on 27 Apr 2013 at 12:48

GoogleCodeExporter commented 8 years ago 
4)What should I do with gras.ellapx.smartdb.rels.EllTube.addprop?
Is it something standart?

Original comment by irizk...@gmail.com on 27 Apr 2013 at 4:59

Attachments:

GoogleCodeExporter commented 8 years ago 
1) Good job with the bookmarks, one problem though - names subsections 
corresponding to the methods should not contain the full class names: 

gras.ellapx.smartdb.rels.EllUnionTubeStaticProj.plot

should be replaced with 

plot

This only needs to be done for classes.

2) addprop is the method of dynamicprops class. You should exclude methods of 
this class in the same way you did for handle class.

3) plot_ia and plot_ea methods for ReachContinuous already feature the new 
plotting functionality so you can go ahead and replace the figures for 
ReachContinuous

Original comment by heartofm...@gmail.com on 27 Apr 2013 at 8:00

GoogleCodeExporter commented 8 years ago 
Regarding 1) - I think the best solution would be using \texorpdfstring from 
hyperref package like this:

\section{\texorpdfstring{gras.ellapx.smartdb.rels.EllUnionTubeStaticProj.plot}{p
lot}}

The result will be "plot" displayed in the bookmarks and full name 
gras.ellapx.smartdb.rels.EllUnionTubeStaticProj.plot displayed in the section 
name.

Original comment by heartofm...@gmail.com on 28 Apr 2013 at 9:35