Jump to content
A.M. Hoornweg

Anything sensible for source code documentation?

Recommended Posts

Hello all,

 

I am sorely missing a way to document sourcecode alongside the sourcecode.

 

I believe that what I'm looking for doesn't even exist. Or?  I find formats like Xmldoc totally obnoxious because it interrupts the source code and the text is never in the place where I need to consult it.  My wide screen has plenty of horizontal space alongside the code.  So why can't I use that empty space to explain what my code is doing and why I wrote it that way, maybe even with nice text formatting, hyperlinks and images? 

  • Like 1

Share this post


Link to post

You don't need to explain what your code is doing. The code ready tells you the what. 

 

XmlDoc is typically used to document libraries for the benefit of the consumer. But you seem to be talking about internal documention.

 

I don't see what's wrong with judiciously used comments on the key methods. After all, the vast majority of methods need no internal documentation. 

Share this post


Link to post

Try Documentation Insight.

It supports both XMLDOC (which I agree makes the source unreadable) and external documentation files:

 

image.png.ea3ec95cd22196d0abb01fb8edca0f10.png

 

I've been using it to generate library help files (in CHM-format) but it can also display the help as tooltips in the Delphi editor.

  • Like 1

Share this post


Link to post
2 hours ago, David Heffernan said:

You don't need to explain what your code is doing. The code ready tells you the what. 

As an expansion to that, what code should have is a comment explaining the why.

  • Like 1

Share this post


Link to post

PasDoc? Or IDE built-in HelpInsight that produces nice HTML-powered hints

Edited by Fr0sT.Brutal

Share this post


Link to post
3 hours ago, Sherlock said:

As an expansion to that, what code should have is a comment explaining the why.

Sometimes it should, sometimes not

Share this post


Link to post
12 hours ago, Sherlock said:

what code should have is a comment explaining the why

Having come back to code from last century I now comment things that may require additional time to read.
Even just a one liner helps when you scan code. I also limit the use of 'With', had some of that a few levels deep before 🙂

 

Share this post


Link to post
19 hours ago, David Heffernan said:

You don't need to explain what your code is doing. The code ready tells you the what. 

 

XmlDoc is typically used to document libraries for the benefit of the consumer. But you seem to be talking about internal documention.

 

I don't see what's wrong with judiciously used comments on the key methods. After all, the vast majority of methods need no internal documentation. 

David, sorry but that's not helpful. This is not some "library" and there is no "consumer".

 
The code I'm talking about is internal and scientific. It does stuff like calculating the 3-d trajectory of curved oil wells, calculates dynamic pressure losses caused by drilling fluid being pumped downhole through a complex drillstring and then up again through the annular space between the drillstring and the wellbore (the flow can behave laminar in some segments, turbulent in others) etc.  and tons of other things.  There is no way to make such code self-explanatory, it requires knowledge of physics, fluid dynamics, geometry and engineering.
 
So I want to document this code in great detail to explain what's going on inside, with hyperlinks to scientific literature, Wikipedia etc.  Because when I retire in ten years, the code must be maintained and enhanced with new fluid dynamic models by my successor and he'd better know what he's doing.   Since the comments are going to be as large as the code itself, a side-by side solution would be ideal for me.  Using Xmldoc or Javadoc/pasdoc only interrupts the flow of things, making it more difficult to read.


 
 
 
Edited by A.M. Hoornweg
  • Like 2

Share this post


Link to post
20 hours ago, David Heffernan said:

XmlDoc is typically used to document libraries for the benefit of the consumer. But you seem to be talking about internal documention.

Read this closely. Here I say that I believe that XmlDoc is not suitable because you aren't doing library documentation for the library consumer. So we are on the same page. 

 

As I expect you know, my work is in the realm of scientific computing. In our case we are simulating the dynamics and loading of pipes and risers. 

 

We document the technical aspects outside the code, using LaTeX so that we can present formulae in a readable fashion. We then cross reference to that document from the code. This works fine for us. I think once you decide that you need formatted equations then that takes you to a separate document. 

 

Anyway, that's how we've settled on doing it. 

Share this post


Link to post

@David HeffernanNice to hear we're in related businesess! I had no way of knowing.

 

Okay, so you're doing the documentation in external documents which you cross reference from the source.  I'm doing that too, but it's for lack of a better solution, because major changes/reformatting of the docs requires locating where the docs are referenced in the source and updating that, too.   It'd be sooo practical to have source and docs synchronized in the IDE somehow.  In full-screen mode I have 50% free space between the right gutter of the source code and the project explorer, it would be great to have a documentation tool fit in there that uses anchors/links in the source code.

 

 

Off topic: I find that the screen real estate of today's monitors is used inefficiently by most IDE's.  Ribbons at the top and logs at the bottom all reduce my view of the document I'm editing.  Recently I had to debug a large and poorly documented piece of source in Visual Studio so I decided to rotate the screen 90 degrees. That was... kind of overwhelming and very gratifying.  If my screens weren't so large I'd keep it that way.

 

 

Share this post


Link to post
2 hours ago, A.M. Hoornweg said:

Off topic: I find that the screen real estate of today's monitors is used inefficiently by most IDE's.  Ribbons at the top and logs at the bottom all reduce my view of the document I'm editing.  Recently I had to debug a large and poorly documented piece of source in Visual Studio so I decided to rotate the screen 90 degrees. That was... kind of overwhelming and very gratifying.  If my screens weren't so large I'd keep it that way.

You can setup any number of internal panel configs aka "desktops" and switch between them. Moreover, unpin the panels and they will auto hide.

Share this post


Link to post
On 3/4/2020 at 1:39 PM, A.M. Hoornweg said:

I find formats like Xmldoc totally obnoxious because it interrupts the source code and the text is never in the place where I need to consult it.

Could not agree more. I spent a week, 12 hours a day to XMLDoc document a mid-sized project. The result was so ugly and unreadable I pushed it to a separate branch only. It is really good to see tooltip insights, or a PasDoc created documentation, but it creates a painful mess for the eye.

 

I'm glad I'm not the only one seeing it this way.

Share this post


Link to post

You know you can collapse not only single XMLDoc sections, but also all of them in one go?

1984322953_CollapseXMLDocs.thumb.gif.76be1add2756149bc190ae40c10f62b0.gif

Share this post


Link to post
1 hour ago, Uwe Raabe said:

You know you can collapse not only single XMLDoc sections, but also all of them in one go?


Just one offtopic question. Is there any undocumented keyboard shortcut for this specific fold? They are many shortcuts (like Ctrl+Shift+K+M) but not for Doc comments.

Share this post


Link to post

If there's an action in the IDE you could try and use GExperts to bind a keyboard shortcut.

Share this post


Link to post

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

×