U++ forum: Welcome to the forum

Search on this site

Search in forums

Home » Community » Coffee corner » in code comments - doxygen

Show: Today's Messages :: Show Polls :: Message Navigator
E-mail to friend

in code comments - doxygen [message #6642]

Tue, 21 November 2006 12:24

qwerty
Messages: 130
Registered: May 2006

Experienced Member

just thought :

using some specificaly syntax offered by upp ide or in comment syntax(aka visual studio 2005 xml comments)

...

to generate documentation from your code or from upp under specifical circumstances

maybee in future

Report message to a moderator

Re: in code comments - doxygen [message #6649 is a reply to message #6642]

Tue, 21 November 2006 18:58

fallingdutch
Messages: 258
Registered: July 2006

Experienced Member

i would like that, too

Bas

Report message to a moderator

Re: in code comments - doxygen [message #6652 is a reply to message #6649]

Tue, 21 November 2006 21:14

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

My idea is to document in parallel using Topic++ and our C++ parser. Similar to doxygen to a degree, but comments are not in the code. This already works pretty well...

In the (near) future, this should be integrated with new class browser - e.g. Assist++ could show help for methods in selection.

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #7219 is a reply to message #6642]

Mon, 18 December 2006 19:23

Balage
Messages: 17
Registered: December 2006

Promising Member

In-code comments tend to be pretty helpful, also the reference generated from it. doxygen is exceptionally good at this.

Maybe consider using it in Upp base source?

As a side note, Assist++ is the very first code-completion feature I have seen in ALL IDEs so far, that really assists in development, and not hinders (I had to turn these things off in other IDEs)!

Assist++ is a GREAT help for me as a beginner, and I think, that by using doxy style docs, Assist++ could even display the /brief of the given function/class, while moving through the available selections. That would be a mighty fine thing! I haven't seen this anywhere yet!

Report message to a moderator

Re: in code comments - doxygen [message #7220 is a reply to message #7219]

Mon, 18 December 2006 19:49

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

Balage wrote on Mon, 18 December 2006 13:23

Assist++ is a GREAT help for me as a beginner, and I think, that by using doxy style docs, Assist++ could even display the /brief of the given function/class, while moving through the available selections. That would be a mighty fine thing! I haven't seen this anywhere yet!

Well, that is what I mean by better Assist++ / Topic++ integration.

BTW, first signs of this comming are already there: if you perform a Query (to get results in lower paint), right click on the results also lists Topic++ themes related to the item.

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #7221 is a reply to message #6642]

Mon, 18 December 2006 20:09

Balage
Messages: 17
Registered: December 2006

Promising Member

Another thing, is that lots of other libs are using doxygen style commenting. So showing those comments in Assist would be nice. How about that?

Report message to a moderator

Re: in code comments - doxygen [message #7222 is a reply to message #7221]

Mon, 18 December 2006 22:26

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

Interesting idea Smile

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #7951 is a reply to message #6642]

Thu, 01 February 2007 18:27

mr_ped
Messages: 826
Registered: November 2005
Location: Czech Republic - Praha

Experienced Contributor

I've been using Doxygen for my own projects, and once you work with it since the very start, it does produce at least average documentation. In case you really pay time and attention, there's no problem to get on good level. (In my eyes most of SW documentations out there are either utter bad, bad or average, so suggesting "good" level is something like admiration)
While Topic++ allows for excellent documentation if enough time and attention is used, I sort of dislike splitting the documentation from the actual code itself.

For high level documentation of course there's no real code, and it starts to be cumbersome to hold this one directly in sources (for Doxygen), and trying out really high abstraction docs was too complex for me. (while I believe that exactly the area where Topic++ can shine)

But when we get back down to commenting the code on low level, I think Doxygen is pretty much ultimate tool.

Report message to a moderator

Re: in code comments - doxygen [message #8057 is a reply to message #7951]

Mon, 05 February 2007 22:57

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

mr_ped wrote on Thu, 01 February 2007 12:27

While Topic++ allows for excellent documentation if enough time and attention is used, I sort of dislike splitting the documentation from the actual code itself.

Well, at least it is in the subdirectory....

Quote:

For high level documentation of course there's no real code, and it starts to be cumbersome to hold this one directly in sources (for Doxygen), and trying out really high abstraction docs was too complex for me. (while I believe that exactly the area where Topic++ can shine)

But when we get back down to commenting the code on low level, I think Doxygen is pretty much ultimate tool.

Yes, Doxygen style is seducing and works well for many cases. At the same time, Topic++ is not where I want it to be yet. I would like to postpone the final judgement until we have new class browser with Topic++ integration.

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #8074 is a reply to message #8057]

Tue, 06 February 2007 10:11

mr_ped
Messages: 826
Registered: November 2005
Location: Czech Republic - Praha

Experienced Contributor

luzr wrote on Mon, 05 February 2007 22:57

I would like to postpone the final judgement until we have new class browser with Topic++ integration.

IMHO it's not as much about what Topic++ *can* do.

It's simply the docs stored not in code, what is main problem.
So whenever you change code, you must run Topic++ to change the help, which will never (ok, with absolutely disciplined programmers it will work superb, but we live in real world) work as good as doxygen's comments which reside inside of the code itself.
Still any lazy programmer will break even doxygen documentation, but the the some-what lazy programmer (who's too lazy to launch Topic++ but not enough lazy to not change comment) will produce better results with doxygen-like approach.

So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.

Report message to a moderator

Re: in code comments - doxygen [message #8075 is a reply to message #8074]

Tue, 06 February 2007 10:27

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

mr_ped wrote on Tue, 06 February 2007 04:11

luzr wrote on Mon, 05 February 2007 22:57

I would like to postpone the final judgement until we have new class browser with Topic++ integration.

Well, these arguments are considered and valid.

On the other side of equation there is comfort of Topic++ editor... I can have advanced WYSIWYG formatting, spell checking, pictures...

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #8076 is a reply to message #6642]

Tue, 06 February 2007 11:32

mr_ped
Messages: 826
Registered: November 2005
Location: Czech Republic - Praha

Experienced Contributor

A bit off-topic: what about spell check inside IDE?
TortoiseSVN does have it when you are adding comment during commit for example, and I found it quite useful. (not even mentioning Firefox 2.0 right now correcting my mistake with "usefull" Wink

)

Of course it would require some level of intelligence to understand C/C++ syntax well.

Having system strong enough for example to find DrawPxiel() (but accept DrawPixel()) would be IMHO considerably handy.

Surely not a high priority. but something to put on the consider-list for future years?

Report message to a moderator

Re: in code comments - doxygen [message #8088 is a reply to message #8075]

Tue, 06 February 2007 20:29

darrs
Messages: 5
Registered: October 2006
Location: New Zealand

Promising Member

Another suggestion.

In the editor you could put a little "Topic++" button in the margin next to global declarations / definitions (I'm assuming Assist++ knows how to recognize these). Clicking that would pop-up a small UWord window to document that function / variable (etc). Hovering over the button could show a pop-up tool-tip with that documentation.

Notes:

a) TheIDE would automatically add a copy of the appropriate function/variable declaration to the start of the documentation.

b) The documentation would be added to the standard Topic++ page for that class / module. Viewing the class via normal Topic++ would show all the combined documentation.

c) Editing the documentation via the margin button would only show the documentation for that declaration / definition. A button in the pop up window would close the pop-up window, start normal Topic++ editor and jump to that declaration in the relevant file.

Cheers,
Darrin.

Report message to a moderator

Re: in code comments - doxygen [message #8091 is a reply to message #8088]

Tue, 06 February 2007 23:26

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

darrs wrote on Tue, 06 February 2007 14:29

Exactly. That is what I mean by "let us finish the idea first" Smile

Mirek

Report message to a moderator

Re: in code comments - doxygen [message #10169 is a reply to message #8091]

Sat, 23 June 2007 03:20

fudadmin
Messages: 1321
Registered: November 2005
Location: Kaunas, Lithuania

Ultimate Contributor
Administrator

For some time I have been dreaming:
Developers enter comments directly into the code.
Users ask questions directly in the code.
CodeEditor or Assist moves those comments into topic but still "keeps the track" and displays them the same way as #ifdef markers and ... all this connected to the forums-wiki hybrid Smile

Or this is too much? Smile

Report message to a moderator

Re: in code comments - doxygen [message #10170 is a reply to message #10169]

Sat, 23 June 2007 07:12

waxblood
Messages: 95
Registered: January 2007

Member

fudadmin wrote on Sat, 23 June 2007 03:20

Or this is too much? Smile

When you see software produtcs ads you always notice the word "integration" well exposed in bold characters.

Well, this is integration!

David

Report message to a moderator

Re: in code comments - doxygen [message #17244 is a reply to message #8074]

Mon, 04 August 2008 15:49

captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA

Experienced Member

mr_ped wrote on Tue, 06 February 2007 04:11

So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.

I know this is an older forum post, but I have come to desire functionality in Topic++ that would automatically bring in doxygen/javadoc style comments from header files along with method/class declarations. Would it be difficult to implement/test out this idea? I find it very easy to update in-code documentation. It is more convenient than external documentation because the code is still fresh in mind and documentation right there. Presenting only a subset of documentation for API purposes through Topic++ would be ideal.

Report message to a moderator

Re: in code comments - doxygen [message #17247 is a reply to message #17244]

Mon, 04 August 2008 17:05

mirek
Messages: 14255
Registered: November 2005

Ultimate Member

captainc wrote on Mon, 04 August 2008 09:49

mr_ped wrote on Tue, 06 February 2007 04:11

Once we have more solid parser, it should be quite possible.

Mirek

Report message to a moderator

Previous Topic:	A Newbie Manual cum Tutorial?
Next Topic:	Ultimate++ Website Logo Text

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

] [

]

Current Time: Mon Apr 28 00:55:38 CEST 2025

Total time taken to generate the page: 0.00821 seconds