docstrings improvements for core modules

[dskhudia]

For evaluator.py, precision.py, serializable.py, state.py, time.py and types.py in composer.core

[hanlint]

LGTM, one small nit on trying to reduce the verbosity of the comments by doing:
:class:.ComposerModel instead of :class:~.base.ComposerModel.

[ravi-mosaicml]

Overall looks good; here are some comments:

• On https://mosaicml-composer--598.com.readthedocs.build/en/598/api_reference/composer.core.evaluator.html#module-composer.core.evaluator, the narrative seems a bit off. Can it read: "For example, CrossEntropyLoss metric for NLP models:" and then no need for the "Example," line below.
• On https://mosaicml-composer--598.com.readthedocs.build/en/598/api_reference/composer.core.time.html#module-composer.core.time, can you add attribute-level docstrings for the Timestamp object? Also, I think it would be helpful to link to the timing guide (will need to merge in dev first), and repeat the table at the top here.
• In https://mosaicml-composer--598.com.readthedocs.build/en/598/api_reference/composer.core.types.html#composer.core.types.MemoryFormat, can you enumerate the options for MemoryFormat in the docstring?
• In https://mosaicml-composer--598.com.readthedocs.build/en/598/api_reference/composer.core.state.html#module-composer.core.state, can we replace the math for train_batch_size to say something like =microbatch_size = train_dataloader.batch_size / grad_accum = optimization_batch_size / (num_devices * grad_accum)? Just not a big fan of double-division.
• For the state, can we also add a note that the Trainer constructs the state automatically?
• https://mosaicml-composer--598.com.readthedocs.build/en/598/api_reference/composer.core.state.html#composer.core.state.State.precision -- precision can also be fp16 now. Perhaps we should just like to the precision enum, since that will always be up-to-date.
• load_state_dict is missing a docstring for the strict parameter.
• I think the docstring for load_model_state is incorrect -- the state_dict parameter should be the model state dict, not the state's state dict. For the strict parameter, keys is a bit vague. Are these parameters? Layers? submodules?
• For get_elapsed_duration, can you elaborate that Time(0, TimeUnit.DURATION) represents the beginning of training, and Time(1, TimeUnit.DURATION) represents when the max_duration has been reached?
• This is not docstring related, but while you're touching this file, can you move the serialized_attributes from being a class-level member to something defined on self.? I realize it's incorrect to have mutable objects defined as a class level parameter. For the serialized attributes docstring, though, can you enumerate which member variables are serialized by default?
• Some types are not autolinking (E.g. types.Batch, Tensors, Timer, ...). In addition, Confusing Scheduler and Schedulers types #510 identified that using our custom plural types in the docstring can be confusing. Can we enumerate this out?
• "Note that the entire state is serialized when the trainer is checkpointed so that it can be used restore the trainer and continue training from a checkpoint. algorithms are able to modify an instance of this class in-place." -- not entirely true. We don't serialize all of the state; the serialied_attributes determines what parts of the state are serialized.

[ravi-mosaicml]

See narrative comments.

[dskhudia]

@ravi-mosaicml : Fixed most of it but need clarification on the following:

Also, I think it would be helpful to link to the timing guide

How do we usually link non-api references? using full path such as https://docs.mosaicml.com/en/v0.4.0/trainer/time.html?

can you move the serialized_attributes from being a class-level member to something defined on self.?

We are not mutating serialized_attributes

Some types are not autolinking

I forced link them. They are not getting picked by the Sphinx automatically.

our custom plural types in the docstring can be confusing. Can we enumerate this out?

Are you suggesting that we get rid of them ?

[hanlint]

How do we usually link non-api references?

You can use :doc: directive, e.g. :doc:Time Guide</trainer/time>

Are you suggesting that we get rid of them ?

No, I think describe the plural options. e.g. Schedulers can be pytorch schedulers, our composer schedulers, or a list or tuple of these schedulers.

[ravi-mosaicml]

Also, I think it would be helpful to link to the timing guide

How do we usually link non-api references? using full path such as https://docs.mosaicml.com/en/v0.4.0/trainer/time.html?

It should be possible to use :doc: or :ref: notation.

can you move the serialized_attributes from being a class-level member to something defined on self.?

We are not mutating serialized_attributes

The deepspeed checkpointing logic does modify serialized_attributes so it can skip serialization of the models and optimizers on the state dict.

Some types are not autolinking

I forced link them. They are not getting picked by the Sphinx automatically.

KK, we can address in a separate PR.

our custom plural types in the docstring can be confusing. Can we enumerate this out?

Are you suggesting that we get rid of them ?

Actually, don't worry about this one. It will depend on #640. Generally speaking, we will want to remove the plural types from the docstrings and instead replace it with x | Sequence[x] It will probably be better to replace this all at once later.

[dskhudia]

@ravi-mosaicml, @hanlint Addressed all comments.