Where to place design documentation in project heirarchy?

[neildarlow]

Hi,

I'll post this here because it's not a programming-specific question. I am developing an application in Gambas3 and I wish to document the design using Gaphor in UML. Where, in the Gambas Project heirarchy, should I save the Gaphor file? In the GUI I see Project and Data, which of those would be appropriate?

TIA,
Neil Darlow

[cogier]

Hi Neil and welcome to the forum.

I suggest you store your files in your program's folder. While in Gambas with your program loaded, from the Tools menu select Browse project.... This will open your program's folder in your file manager. If you change any files while the Gambas IDE is open you may need to Project>Refresh to show the newly created file(s) under Data in the IDE.

[BruceSteers]

In your project folder if you show all the folders/files you will find a few hidden directories.

Basically the only usable hidden directory will be one called .public
You can put things in the .public directory or you can create your own non-hidden folders.

Do not use the other hidden folders.
.gambas is where the compiled binaries reside
.src is for ONLY gambas source code files
.hidden is for when making controls
.action is control action data.

Any files or directory of files you create in the project root folder that is not hidden (begins with .) will be included in your executable MyProject.gambas file or when making a source archive file.
Any .hidden folders or files are not included. (except for folder .public)

Access files like pwd is project dir

File.Load("./.public/myfile.xml")
File.Load(".public/myfile.xml")

Also note that you will be able to load files into your program but some types of access will not see the files so they may need to be copied to a temporary location first..

Dim sFile As String = File.SetExt(Temp(), "xml")

Copy "./.public/myfile.xml" To sFile

Shell "some-command " & sFile

Hope that helps.

[thatbruce]

Aw man! I've been using .hidden for centuries now for documentation and a lot of other junk as well. AFAIK, apart from the controls matter, all it means is that the content doesn't get included in the executable archive. Which is really handy if one uses, say, a UML tool that creates ginormous "project" files, or say a truckload of LO/OO documents, spreadsheets etc.
Has something changed that I may have missed?
Also, I thought ".public" did get included in the executable? Not that I know as I've never used it or found a use for it. What's it for?
I might also add, .hidden allows us here to (with a few tweaks) to exclude a lot of "private conversations" stuff out of the package builder. Is that still a possibility? I ask because I haven't checked lately but it may explain some strange conversations lately.

b

[BruceSteers]

Well yeah , horses for courses i suppose.
That's a handy thing to use .hidden to put stuff you do not want to include.

And YES .public contents does get included in the executable (that's what i said) it's the only .hidden folder that does.
Although there is now a new option in the project config to "exclude .public dir" if you don't want it included.

You can test/list an executable's contents with gba3 -l ExecutableName.gambas

From what i can tell if you "create a package" archive then .hidden contents get included but if you make an executable then the .hidden contents will be missing (but if the executable is run from the project dir it will still find them)

I concluded the .hidden folder is for IDE use only. You put your custom control icons in there so when editing the project the IDE uses the icons, but after making an executable the icons for the IDE are not needed anymore.

[BruceSteers]

So to summarize the initial question "where in project hierarchy" ?
Specifically the IDE listed folders

Project links to the directory named .hidden (see previous posts for uses of this folder)
Source links to the .src directory (only for your projects gambas source code files)
Data links to the projects root directory (This is probably where you want to add folders/files)

[neildarlow]

Thank you for your replies. I'm leaning towards a documentation (Docs) folder within Data.

Regards,
Neil