| Author |
 Topic  |
|
|
bugfix
Tomato Guru
Germany
324 Posts |
 Posted - Feb 03 2007 : 03:42:07 AM
|
would it be possible to add more "document" commands?
im thinking of smth like "document this" command which checks for the type like class, struct, enum, variable,... and uses the appropriate autotext then.
searched forum but didnt find anything so sorry if its a dupe.
-bugfix |
http://www.mf-sd.de |
|
|
feline
Whole Tomato Software
United Kingdom
18939 Posts |
Posted - Feb 04 2007 : 08:22:41 AM
|
I can see how something like "Document Class" would be useful. Are you thinking of one autotext entry for all of these, or a separate autotext entry for each of them?
I would rather not suggest adding 14 new refactoring autotext entries, but I have the feeling that one entry is not going to work so well for all items. |
zen is the art of being at one with the two'ness |
 |
|
|
bugfix
Tomato Guru
Germany
324 Posts |
Posted - Feb 04 2007 : 11:05:14 AM
|
havent fully worked this out but i guess you don't need that much autotext entries at all.
"document type": for classes, structures, enums, typedefs
"document variable": for vars and enum members.
"document preprocessor": ifdefs, pragmas, defines
"document method": methods
have i missed smth?:)
basically there should be only one menu entry "document this" which then selects the right autotext. there might be the need to introduce some more autotext vars though.
|
http://www.mf-sd.de |
|
|
|
sl@sh
Tomato Guru
Switzerland
204 Posts |
Posted - Feb 05 2007 : 04:18:30 AM
|
If you use one method for "document class" and "document typedef" then apparently you are not thinking of adding members to the documentation? If this is the case, there's nothing much to "refactor" anyway, except for the symbol name itself. I'd say a self-defined autotext entry would be just as well, you'd only have to copy the symbol name into it afterwards.
OTOH, if you want a decent class documentation, then adding the public methods (the class' interface) would make a lot of sense, but since structs don't usually have 'public' members (or members that are *not* public, to be more precise), and typedefs don't have members at all, you'd need a seperate document method.
That said, different people have different documentation needs, so the easiest solution (maybe not for the programmers, I don't know) would be to define a number of context sensitve symbols that VA users could use to define autotext entries. I think there's already a case for that request, no? |
|
|
|
bugfix
Tomato Guru
Germany
324 Posts |
Posted - Feb 05 2007 : 10:28:03 AM
|
| i didnt say that its not possible w/ autotext already. its more like why is there only document method? hence the "document this" and not n different autotext shortcuts. its a job vax can do. |
http://www.mf-sd.de |
|
|
|
feline
Whole Tomato Software
United Kingdom
18939 Posts |
Posted - Feb 05 2007 : 2:25:37 PM
|
When I first read this request I remembered my last job, where a rule was introduced that all classes had to have a doxygen format comment explaining the purpose of the class. Since this was supposed to go above the class there would be no scope / context for VA to respect, not if you want the class name automatically inserted into the comment.
So with this in mind the ability to have an autotext entry that would pick up and use the class name is appealing.
I am not quite so sure about document variable, but only having one command for all document jobs is a compelling argument 
case=4932 |
zen is the art of being at one with the two'ness |
|
|
|
bugfix
Tomato Guru
Germany
324 Posts |
Posted - Feb 05 2007 : 2:38:40 PM
|
| heh, thats the reason ive asked for it. i have to comment basically everything w/ doxygen style at this job now. f**king insane if you ask me. i spend more time documenting than writing code but as long as i get paid...:) |
http://www.mf-sd.de |
|
|
|
feline
Whole Tomato Software
United Kingdom
18939 Posts |
Posted - Feb 05 2007 : 2:52:36 PM
|
Ever worked on code without any comments or documentation? *yuk*
You do need to strike a sensible balance though. The problem I have run into is what is obvious to one person who knows the area is just incomprehensible to someone else who does not know the area. Or what normally happens, I know what my code does when I write it, but not when I come to fix it 3 years later *rolls eyes* |
zen is the art of being at one with the two'ness |
|
|
|
bugfix
Tomato Guru
Germany
324 Posts |
Posted - Feb 05 2007 : 3:02:44 PM
|
sure, i ve been doing reverse engineering binaries for like 6+ years:)
anyways im using self-explanatory names for everything, short functions and document complicated parts. but documenting every single member var, enum, define you name it what else is just a bit too much. im a developer and no book writer for christ sake:)
If it was hard to write, it should be hard to understand and even harder to modify! |
http://www.mf-sd.de |
|
|
|
feline
Whole Tomato Software
United Kingdom
18939 Posts |
Posted - Feb 05 2007 : 3:08:43 PM
|
I could have used you 6 months ago, when I was trying to reverse engineer a database It got bad when I was reading through the comments in the stored procedures and realised I knew more about how the database worked than some of the people programming it.
That level of comments... yep, that is stupid. Can you get away with default descriptions you can just copy and paste? |
zen is the art of being at one with the two'ness |
|
|
|
bugfix
Tomato Guru
Germany
324 Posts |
Posted - Feb 05 2007 : 3:12:04 PM
|
| thats what im actually doing as i really doubt anyone will ever read the documentation anyways:) |
http://www.mf-sd.de |
|
|
|
sl@sh
Tomato Guru
Switzerland
204 Posts |
Posted - Feb 06 2007 : 04:09:58 AM
|
Unfortunately, IME many variable or method documentations look like this:
int foo; // stores foo value
char* bar(); // reads bar value
No hints as to what those variables or methods refer to, what values to expect, where they are needed, etc.. Mostly those symbols also use some kind of abbreviation style that might have been sensible to the original programmer 5 or 10 years ago, but is completely unknown to the current developers, or at least misleading or dubious. I've also noticed that different programmers often use the same symbol name locally for quite different entities. If you have nothing but the symbol's name and type for documentation, no amount of autotext will help fixing these kinds of problems.
Whether autotext helps alleviating this style of documentation will still depend on the developers' effort to select sensible names and fill in the appropriate parts in the autotext documentation. It will still be very helpful for any programming team that spends some effort on actually reviewing source code. (yes, these do exist!) |
Edited by - sl@sh on Feb 06 2007 04:10:57 AM |
|
|
|
ianw
New Member
United Kingdom
4 Posts |
Posted - Mar 08 2007 : 10:30:23 AM
|
As a developer using VB.NET, C# as well as C++, I'd just like to add in a request for Document Property, Document Interface etc.
- Ian |
|
|
|
feline
Whole Tomato Software
United Kingdom
18939 Posts |
Posted - Mar 08 2007 : 12:51:03 PM
|
| A very good point, I have made a note of this on the case for reference |
zen is the art of being at one with the two'ness |
|
|
|
n/a
deleted
1 Posts |
Posted - Apr 18 2007 : 07:49:49 AM
|
I would like to use doxygen comments also.
But when creating libraries you only "reveal" the include-file and I would like to document class, variables and functions there.
I think "Kings Tools" was quite good at creating doxygen-comments for most types with a single "document this" type of command. |
|
|
| |
Topic |
|
Refactor Document This
