Document To Make Things Public - Privacy and (i18n-ed) documentation #1816
amitu
started this conversation in
Ideas & RFCs
Replies: 2 comments 1 reply
-
Not too happy with |
Beta Was this translation helpful? Give feedback.
0 replies
-
I like the idea of documenting We can also use these doc files for static analysis, and maybe even enforce having corresponding doc files for every ftd source file for "system packages". If we do this then the folder name |
Beta Was this translation helpful? Give feedback.
1 reply
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
We have a few proposals in the past about how we "export" things, and how make things public or private.
$public$
_
eg_foo
are private--export
I have yet another proposal. This proposal is meant to supersede the other ones listed above.
Documentation Syntax
We are going to use
;;;
as doc comments.Documentation Only Definitions
Documents can be included as part of the original code itself. Or we can store documentation in a separate file, under the doc folder heirarchy. If a component is defined in foo/bar.ftd, its documentation path will be
doc/foo/bar.ftd
, ordoc/<lang-code>/foo/bar.ftd
.Documentation Can Be Internationalised
If fastn.package says:
We assume the folders inside
doc
folder arelanguage codes
.If documentation is inline with where the component etc are defined, the
default-documentation-language
tells us what is the language it is meant to be written in. The default language documentation can be stored infoo.ftd
or indoc/en/foo.ftd
. For a project you can not mix and match, either all default language documentation would be in respective files where things are defined, or all the documentation would be in one of the doc folder.For the purpose of privacy, we will only look for default language documentation.
If some symbol is not yet translated, the corresponding text from default language will be used, so things can be incrementally be translated, without having to copy paste everything.
Document To Make Things Public
The only way to make something public is by documenting it. Any component, or type that is documented in doc.ftd is considered public. If you want to keep documented stuff private, you have to add PRIVATE keyword in the doc string. When documenting a component, all its fields must also be documented if they are supposed to be use publicly.
A component with (even one) private field without default value can not be public, and must be marked PRIVATE.
Similarly for functions, records, global variables, assets.
fastn doc
This command will start http server, which when you go to will show documentation of the package (and all its dependencies).
fastn doc --test
will test examples of all the docs in the current package (and make other sanity checks, like translation docs only document what is actually present in original language, etc).Documentation Examples To Be Visual Tested
All examples in documentation across all languages will be visual tested as well.
System Package
If a package is implementing a system package, then the documentation must not be in that package, and system package documentation would be used for all packages implementing that system package.
Beta Was this translation helpful? Give feedback.
All reactions