[prev in list] [next in list] [prev in thread] [next in thread] 

List:       quanta-devel
Subject:    Re: [quanta-devel] Annotation support
From:       Jens Herden <jens () kdewebdev ! org>
Date:       2005-04-23 13:53:02
Message-ID: 200504232053.02934.jens () kdewebdev ! org
[Download RAW message or body]

Hi Andras,

> > All this brought people to invent tools like Doxygen, so that you can
> > comment your code inside of the document.
>
> Hm, Doxygen. I forgot about it. Can it work with XML files?

I have no idea if Doxygen works with XML. This was just to make clear in which 
direction my thinking goes. 

> > So what are the problems you want to solve?
> >
> > 1. You want to browse the annotations of one file and be able to jump
> > to a line.
> > We have this concept already, it is called structure tree and I see
> > no problem in adding a subtree for comments there.
>
> The structure tree can be very big. Also not all comments are
> annotations.

Right, maybe the structure tree is not a good place. Maybe we should think 
about removing everything from the structure tree that has no real tree 
structure. Link the links, functions etc. these are simple lists and could 
better find another representation in the GUI than a tree. 

On the other hand users are used to this concept and if you would just add 
another subtree it should be create not much trouble to learn this. 
Especially if only the tagged comments come there.

> > 2. You don't want to see all comment, just the important one.
> > Lets use a kind of tag system to filter the important one out. (like
> > @annotation inside of the comment or so)
>
> That makes more sense.
>
> > 3. You want to have all comments inside of the project available.
> > This would mean parsing all files in the project and would suggest to
> > do this when we move to KDevelop. There should be some kind of
> > background parsing.
>
> I'm not sure they have background project parsing. The CPP parser is
> threaded AFAIK, but the project parsing is not.

Well, than we should invent it ;-)

> > The result should be stored in the project file
> > not in the filesystem so that on startup no rescan is necessary.
>
> Now I have to say that storing such information in the project file is
> not anymore different then storing in an external file (except that it
> is faster to scan).

Well I see some positive effects in not storing them in the filesystem but in 
a file:
- faster scan (as you said)
- less clutter in the folders
- less opening and closing in remote filessystems

> > 4. You don't want to see your comments during normal editing, just
> > the icon as hint.
> > This could be something that might Kate implement inside of the code
> > folding stuff. Just always fold comments away and give a tooltip if
> > you stay over the folded block. Otherwise Quanta could hide it form
> > the editor. But my favorite solution would be a action in Kate to
> > hide/show all comments.
>
> The problem is that in most languages comments can be one or multiline.
> In case of multiline comments hiding may be possible, for one line
> comments I'm not sure it even makes sense.

For oneliner it does not make sense at all since you need one line to unfold 
it again. Is there a codefolding interface so that Quanta could fold the 
comments away?

> > I think we should drop this implementation and think about another
> > approach to get what you want. Don't invent new features for problems
> > that are already solved but improve the handling of the current
> > solution is the way to go.
>
> I don't want to drop the whole feature, but change the storing of the
> annotations. ;-) 

I did not say that you should drop the feature, just this implementation ;-)

> What do you think about this: 
> 1) store inside the document as comments (in comment nodes), as you
> suggested, and use the special tag @annotation. So in case of XML:
> <!-- @annotation My comment --> (can be multiline as well) or
> <!-- something @annotation My comment --> (the annotation is the same).
> In case of PHP:
> /* @annotation My comment */ or
> /* something @annotation My comment */ or
> // @annotation My comment
> and so on.
>
> This solves the problem of line shifting. moving and editing outside of
> Quanta. But doesn't help in parsing the whole project for comments.

good!


> 2) in the project file (or the session file?) create an index with the
> files having annotations in the form of:
> <annotations>
>  <item url="filename" time="timestamp" lines="11, 23, 50" />
>  ...
> </annotations>

I can not clearly remember what was supposed to go into the project file and 
what into the session file. So the project file is what you have in the 
remote project and the session file can stay local, I would suggest the 
session file, because you loose nothing if you loose the annotations. You can 
rescan you files. 
I wonder if we should store the annotation itself there not a reference. This 
would mean more data in the file but no need to rescan the files on startup 
to show the global annotation list. 
Please store also the files that have no annotation inside, so that you will 
not scan them again and again because they are not in the list. 

> - On startup only the files from the project not under <annotations> or
> those having a different timestamp than stored there are scanned.

If you create a background parser this is good. Maybe this is the point where 
you want to get involved in programming with threads? 
But I think the first step could be easier. If we assume that most of the 
editing is done inside of Quanta we could do the scanning on opening a text 
file (when the parser is always working) and update the annotation info then 
(if they were changed at all). On save we would update again.
This would mean that we don't have the right information if the file was 
changed outside or the annotation got lost because you session file was lost. 
But during your work, step by step, you get them back. 
If we also add a action "scan project for annotation" the user can update at 
any moment. 
This would not impose some hidden performance penalties for the project 
scanning but gives the user control over the right moment to do it. And I 
guess in most of the cases it would be sufficient to update the info on the 
fly. 

> - Whenever a file is saved, added to the project,  updated from CVS is
> performed, it is scanned for annotations and the project file is
> updated.

Yes, adding to project and updating should trigger a scan.

> - editing of the annotations can be done either by entering the comment
> manually or editing in the annotations view. I'm not sure if in this
> case we need the context menu entry or not.

I rather would not create a new dialog for this. I would suggest to create a 
toolbar button for a comment with annotation. So people can assign a shortcut 
and can type right away without disturbance form a dialog. 
If you want a dialog it might be an idea to enhance the tag-editor dialog so 
that you can invoke it on an comment. There should be a tickmark if you want 
a annotation tag inside and a multiline editor to type your comment. 

> What do you think about this proposal?

I like it and I would even more like it if you could keep in mind that this is 
a good candidate for a KDevelop plugin. So please don't tie it to closely to 
the rest of Quanta. Think about: new feature == new class(es)

> BTW, no problem if you disagree. I may have worked a little in plus with
> this, but whatever. I can bare it. ;-) And you usually have good ideas.
 
I feel relieved to read this :-)

Jens
_______________________________________________
quanta-devel mailing list
quanta-devel@kde.org
https://mail.kde.org/mailman/listinfo/quanta-devel
[prev in list] [next in list] [prev in thread] [next in thread]