Anything sensible for source code documentation?

[A.M. Hoornweg 144]

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? 

[David Heffernan 2353]

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. 

[Anders Melander 1815]

Try Documentation Insight.

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

 

 

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.

[Sherlock 663]

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.

[Fr0sT.Brutal 900]

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

Edited March 4, 2020 by Fr0sT.Brutal

[David Heffernan 2353]

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

[FredS 138]

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 🙂

 

[A.M. Hoornweg 144]

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 March 5, 2020 by A.M. Hoornweg

[David Heffernan 2353]

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. 

[A.M. Hoornweg 144]

@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.

 

 

[Fr0sT.Brutal 900]

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.

[aehimself 399]

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.

[Uwe Raabe 2064]

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

[DiGi 14]

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.

[David Hoyle 68]

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