Giters

PascalGameDevelopment / SDL2-for-Pascal

Unit files for building Free Pascal and Delphi applications using the SDL2 library

Home Page:https://pascalgamedevelopment.github.io/SDL2-for-Pascal/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Folder names and structure of extensions of the pure translation project

Free-Pascal-meets-SDL-Website opened this issue · comments

commented

As the project grows more complex, we need to decide on senseful names and folder structure of project extensions (e. g. examples, tests, docs,...) which are not directly related to the original sdl2 package. Otherwise the main folder will be polluted with all kinds of different files which complicates everything unncecessarily.

The main goal is to make clear from the folder names that these contain files which are not directly related to the original sdl2 lib.

My proposal would be a prefix "pascal" to make this clear:

E.g.
\ (main source, as is)
\pascaldocs\
\pascalexamples\
\pascaltests\

The substructure in these folders could then be as expected:
\pascalexamples\renderbitmap\
\pascalexamples\handleevents\

Please let us discuss if there are other and/or better ways to keep the files ordered.

commented

I don't think there's much sense in prefixing stuff with pascal; it's pretty clear from the repo's name and README that this is just a header translation and not some new, extra library. I wonder, though, if it wouldn't be best to move the unit files themselves from repository root to /src or maybe /units.

Speaking of docs, currently we're mostly just taking the original C source and leaving the original doc-comments as-is. I think this is rather pointless, since I imagine that someone looking for information on how to use SDL will just consult the official documentation at wiki.libsdl.org, rather than browse the .pas / .inc files. As such, I think there's two things we could do:

  1. Try to convert the documentation to FPDoc format so we can generate a reference page similar to FPC's official docs.
  2. Just remove the docs from the source, limiting the files to containing only actual type/function definitions.
commented

I don't think there's much sense in prefixing stuff with pascal; it's pretty clear from the repo's name and README that this is just a header translation and not some new, extra library. I wonder, though, if it wouldn't be best to move the unit files themselves from repository root to /src or maybe /units.

Well, I see your point. I'm also not fully happy with a prefix "pascal" either,

About /src or /units. I strongly like to suggest /units. It is clear from the name that there will be Pascal units in there and it cannot be confused with the folder /src of the original SDL2 package.

I'd like to suggest, too, that we add a folder /include where we put all the inc files. This would be highly in accordance with the original package. What do you think?

Speaking of docs, currently we're mostly just taking the original C source and leaving the original doc-comments as-is. I think this is rather pointless, since I imagine that someone looking for information on how to use SDL will just consult the official documentation at wiki.libsdl.org, rather than browse the .pas / .inc files. As such, I think there's two things we could do:

1. Try to convert the documentation to [FPDoc format](https://www.freepascal.org/docs-html/fpdoc/fpdoc.html) so we can generate a reference page similar to FPC's official docs.

2. Just remove the docs from the source, limiting the files to containing only actual type/function definitions.

I disagree about the notion that everybody will always look up everything on the wiki pages, but never in the code itself. Lazarus will display the comments above a function declaration fairly quickly and it can help a lot, especially if you are not about to study the package but just need a quick reminder of the return values or something similar.

So, I strongly suggest to go with way 1. - I will add this to the todo list.

commented

Proposal of a structure:

\ for README, LICENSE, ...
\units\ for sdl2.pas, sdl2_image.pas, ...
\units\include\ for all the inc-files used by sdl2.pas; Note: No plural "includes" to be consistent with original C pack folder name
\tests\ for test programs used by GHA
\tests\test1\ for each test a subfolder
\examples\ for sdl2/pascal example programs
\examples\example1\ for each example a subfolder
\docs\ for documentation/FPDocs

What do you think?

commented

I'm not really sold on the /units/include part. Other than that, full support.

commented

Not sure if I'm all too happy about all the file histories gone now... Forgot about that...

Anyway, for the project altogether, it has a better structure now.