Confusing/inconsistent behavior in enforcing requirement for File/LibFile block at file start.

[AndrewTasso]

Summary

Currently, the docs state that all files must have a File: or LibFile: block at the start of the file
. However, the parser does not explicitly enforce this. Instead, if either of those blocks have not been previously encountered, it'll automatically inject a LibFile block upon first encountering one of a handful of other blocks (e.g. Section, Includes, etc.).

This issue is further compounded when a File/LibFile block is inadvertently added after one of the blocks which results in an automatically generated LibFile block. This causes an error to be displayed without a clear indication that one had automatically been generated.

I ran into this issue when I accidentally created a File block after a FileGroup block and couldn't understand how to resolve the issue until I reviewed the source to determine how the application was behaving behind the scenes.

Steps to reproduce

1. Create a file, test.scad, with the following content

// FileGroup: Test Library
// File: test.scad

2. Execute

openscad-docsgen <path to test.scad>

Expected behavior

Either

• Explicitly provide an error when a File/LibFile block is not the first block of a file. (To be consistent with the docs)
  • Effectively strict by default

or

• Print a warning to console to indicate that a File block has been auto-generated in the absence of one
• Ignore subsequent File blocks or overwrite existing File block in the parser if they're encountered (providing a warning when doing so)

Actual behavior

The application displays an error indicating that a File/LibFile block has already been specified, when it has not.

Output:

Parsing...
  test.scad
!! ERROR at test.scad:2: File/Libfile block already specified, while declaring block: "File"

[AndrewTasso]

I just had a thought!

A more drastic (and breaking) solution to this could be to eliminate explicitly declared File/LibFile blocks altogether. The parser already appears to handle all relevant scenarios in which a File/LibFile block is warranted/needed (but has not been previously declared), and automatically pulls the file info from origin.

The downsides to this are it would eliminate scenarios in which someone would want to declare the block with a different file name than actually used, and having to make a decision on whether File or LibFile should be used.