Documentation
=============

Documentation is key. You **must** document. Even if you are writing only for yourself. Code you wrote a month ago is code that was written by someone else and just as un-understandable.

Update your ``app/components/login-page.js`` to include some documentation:

.. code-block:: js

    import Component from '@glimmer/component';
    import { tracked } from '@glimmer/tracking';
    import { action } from '@ember/object';

    /**
    * Provides backend functionality for Login Page Component used by Login Route
    */

    export default class LoginPageComponent extends Component {
        /**
        * Required variables
        * The untracked variables help update the UI.
        */
        @tracked email = '';
        @tracked password = '';
        @tracked loginInvalid = false;
        classLabel = 'text-danger';
        classInput = 'is-invalid';
        classSpan = 'invalid-feedback';

        /**
        * Handles the user submitting the login form.
        * Suppresses standard behavior.
        * Tests email/password and updates the UI.
        */
        @action
        login(event) {
            event.preventDefault();
            if (this.email === 'test@example.com' && this.password === 'password') {
                this.loginInvalid = false;
            } else {
                this.loginInvalid = true;
            }
        }

        /**
        * Handles the user typing in the email/password input fields.
        * Resets the ''loginInvalid'' property to improve usability.
        */
        @action
        typing() {
            this.loginInvalid = false;
        }
    }




The documentation block at the top demonstrates the use of `JSDoc`_ for documenting JavaScript functions, but you do not necessarily have to use these. The most important thing is to document the logical flow of your code, not the specifics. There is no need to explain what a simple ``if`` statement does, but you do need to document why there is a ``typing`` action and what it does in the larger flow of the application. Similarly, for generic functions, you need to document what goes in and what comes out, but not how it actually works. The exception to that is if your code is very complex, then you might also want to include some in-line comments.

.. _`JSDoc`: https://jsdoc.app