How to create a detailed description of a program

General Programming
1

Is there a template or approved method for detailing how a program “works”? Maybe like the comments in the code compiled into a document that’s human readable to a person wanting to know in detail how a program does what it does?
Or a describing an uncommented program or perhaps in the design stage before the program is written!
I’ve seen automatic ones for JavaScript… anything like that for Xojo or C#?

2

IIRC There’s something to do this for Swift…

1 Like
3

There is(was) as program called JAZZY the took markup comments from an Xcode project (ObjC or Swift) and created a nice HTML document complete with links and such. Before I walked away from Xojo I was in the process of doing a similar app for Xojo projects, but that has long since been abandoned

2 Likes
4

FastAPI is a web framework for Python’s Asynchronous Server Gateway Interface and it uses type annotations and comments to autogenerate both data validations and documents.

That’s not the only thing that happens magically under the hood either, there are other nice features like JSON encoding / decoding that are just handled for you too.

If you use uvicorn as the server during development it will also monitor your code for changes and automatically reload to save you having to restart the server:

$ uvicorn main:app --reload

If you use uvicorn to run your app you can easily make it multiprocess too:

$ uvicorn main:app --workers 4

I’ve only recently started experimenting with FastAPI but so far there’s a lot to like.

5

Visual Studio and JetBrains Ryder (and I assume VS Code) have long been able to generate IntelliSense from specially formatted comments in C# and VB.NET code. I’m pretty sure that programs exist to formalize that as documentation; I just haven’t had much of a need for it thus far.

2 Likes
6

I sort of stumbled on this using /// in C# :slight_smile:

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

lots of other markup tags as well

1 Like
7

One
W
At to do this is to ask chat gpt or another AI application to review source code and explain how it works and suggest improvements.
Eg “ Please take a look at the following code and write a detailed explanation that could be understood by a 20 year old university student”

8

just for the H of it, I tried was “supcumps” suggested… although the AI was not capable of explaing an entire application (too long). I did give it a complex Swift Enum from a Solitaire game I am writing, and dang if it wasn’t spot on with the explantion, even describing things for which there really was no context…

The explanation wasn’t in a “documentation” format, but more a conversational one, but still the accuracy was impressive

9

I’ve found that changing the prompt can do wonders.

“You are writing formal documentation to be read by software developers. Analyze this file/method/whatever and create documentation for it.”

I did that for my travel blog “Take this text and convert it into a blog style post”. And I’ll be damned if it doesn’t get 90% there.

1 Like
10

the main problem is size of code provided. unless it can analyze the entire program, it cannot create complete documentation, but it is an impressive start

1 Like
11

Our work supplied LLM can accept files. Not that I’ve tried that but I’ve seen others do it. I doubt it can look at a whole project of files but I’m sure that’s just a matter of time.

1 Like