Document To Make Things Public - Privacy and (i18n-ed) documentation

[amitu]

We have a few proposals in the past about how we "export" things, and how make things public or private.

• $public$
• component arguments starting with _ eg _foo are private
• --export
• re-export syntax

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.

;;; -- doc.component: foo should be used when you are in need of foo
;;;
;;; three colons means this is a document comment.
;;; 
;;; -- ftd.image: we can use image etc in documentation of course
;;; src: $assets.files.example.png
;;;
;;; -- doc.example: this is caption of basic example of foo
;;; 
;;; this is some more explanation of this example of foo (body of doc.example)
;;;
;;; -- foo: hello
;;;
;;; -- end: doc.example
;;;
;;; @PRIVATE -- since we added this line, this is documented private component, a documented
;;; component by default is public
-- component foo:
;;; you should pass title to foo, this field is required. 
;;; 
;;; -- doc.example: we can show examples of fields also
;;; <example omitted>
;;; -- end: doc.example
caption title:

;; body of component must be empty if it is in doc/* hierarchy.

-- end: foo

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, or doc/<lang-code>/foo/bar.ftd.

Documentation Can Be Internationalised

If fastn.package says:

-- fastn.packge: my-package
documentation-is-translated: true
default-documentation-language: en

We assume the folders inside doc folder are language 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 in foo.ftd or in doc/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.

[amitu]

Not too happy with @PRIVATE syntax.

[siddhantk232]

I like the idea of documenting foo/bar.ftd in doc/foo/bar.ftd. It's similar to what we have in C/C++ with header files or OCaml's .ml (module implementation) and .mli (module interface).

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 doc/ does not clearly explain the intent.

[amitu]

If we do this then the folder name doc/ does not clearly explain the intent.

I did not get this bit.

In general you system package bit I missed. For packages that "implement" a "system", the documentation must not be present in the package, but in the system package alone. I am updating the description with this.