Re: [Pasdoc-main] What do you think about a @file option?

[Michalis K. <mic...@gm...>]

silvioprog wrote:
> You can use "@file 'your-doc.file.txt'" or "@file", this last option
> will search the file containing the class and method name like
> "TMyClass.MyMethod.txt" in current directory or specified via @dir.
> 
> Is it an good idea or I'm daydreaming? =/
> 

(Sorry for such delay in answering! Busy times....)

Basically, I see that most of your use-cases are covered by the @include
tag, that allows to include a description from a specified file. See
http://pasdoc.sipsolutions.net/IncludeTag . This basically does what
your @file option would do.

And to avoid having to write @include... tag too often, you can use
--description command-line option, see
http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . This allows to
place (multiple) descriptions in an external file, and they will be
automatically used by PasDoc.

So, some of needs are already implemented:)

What is missing is the automatic guessing of filename to include. That
is, in your proposal, one can write @file without a parameter, and then
the name of the file is automatically guessed from the identified name.
I think that this can be implemented as just an extension of @include
tag? When the parameters are empty, then guess the file name. The
contributions are most welcome:)

In your proposal, you also add command-line options and tags to specify
the directory where to look for files. These seem like good ideas to
organize descriptions, I only have small notes:

1. --doc-source-path= should rather be --include-doc-dir= or such? Just
keep "include" in the name, to make it clear it's used with @include.

2. For similar reasons, @dir tag should be called @includeDocDir . Keep
the phrase "include" inside.

3. The effect of @includeDocDir should only apply to the current unit.
Otherwise parsing order, command-line order, cache may all cause problems.

Best regards!
Michalis