Improvement to usage docs

[dmeehan1968]

I found it misleading that the usage docs state that you can call ts-auto-guard on a source file without either specifying --export-all or the requirements for comments to indicate which are exported. It would be clearer for the docs to give the --export-all usage first, then clarify that it can be controlled on a case-by-case basis via comments.

Also, nowhere does it state that the interfaces must be exported. Internal interfaces are a valid use case, but of course the export is required due to the nature of the generated guard implementation. I don't think that can be resolved without inserting the guards into the original source which creates its own issue, so a usage not explicitly stating that only exported interfaces will be processed would be helpful.

[rhys-vdw]

Hi there, sorry for the slow reply. Start of the year etc.

It would be clearer for the docs to give the --export-all usage first, then clarify that it can be controlled on a case-by-case basis via comments.

Honestly I'd rather not bring this to the forefront as it's better practice to use the explicit annotation IMO.

Also, nowhere does it state that the interfaces must be exported. Internal interfaces are a valid use case, but of course the export is required due to the nature of the generated guard implementation.

Yes, right now it's only in a comment in the example code. PR welcome.

I don't think that can be resolved without inserting the guards into the original source which creates its own issue, so a usage not explicitly stating that only exported interfaces will be processed would be helpful.

You ought to be adding the guard annotations to the original source, of, if that's not desirable, create a new source file that imports and exports them:

import { Foo } from "./foo";
/** @see {isFoo} ts-auto-guard:type-guard */
export Foo;

An improvement that could be made here is to check every single declaration at document root for the annotation and log a warning/error if it's not exported.

In any case there are surely improvements that could be made to the doc. A PR to prevent confusion in future would be more than welcome.

[rhys-vdw]

The obvious thing that's missing here is a code snippet for the Person declaration (including export and annotation) in the Usage section.