Open GoogleCodeExporter opened 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
Original comment by irizk...@gmail.com
on 11 Apr 2013 at 2:14
Attachments:
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
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
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
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
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
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
>> 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
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
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
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
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
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:
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
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
elltool.doc
elltool.demo
elltool.logging etc..
Original comment by irizk...@gmail.com
on 18 Apr 2013 at 3:35
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
Oh,so simple.
Thanks.
Original comment by irizk...@gmail.com
on 18 Apr 2013 at 4:03
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
Should i add new examples in doc\mcodesnippets?
Original comment by irizk...@gmail.com
on 18 Apr 2013 at 8:31
Attachments:
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
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
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
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
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
Original comment by heartofm...@gmail.com
on 20 Apr 2013 at 9:09
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
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
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
>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
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
[deleted comment]
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
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
Original comment by heartofm...@gmail.com
on 21 Apr 2013 at 1:34
Original comment by irizk...@gmail.com
on 23 Apr 2013 at 6:33
Attachments:
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
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:
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
1)Oh, I was sealed. elltool.linsys.LinSysFactory.empty, I meant.
Original comment by irizk...@gmail.com
on 26 Apr 2013 at 4:49
"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
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
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
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:
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
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
Original issue reported on code.google.com by
heartofm...@gmail.com
on 22 Mar 2013 at 5:57