[PATCH 07/13] Add documentation to the simpleline library for TUI

Chris Lumens clumens at redhat.com
Thu Aug 9 18:51:49 UTC 2012


I hate being picky about typos and such, but it's documentation.

> diff --git a/pyanaconda/ui/tui/simpleline/base.py b/pyanaconda/ui/tui/simpleline/base.py
> index 573f28b..0c9f750 100644
> --- a/pyanaconda/ui/tui/simpleline/base.py
> +++ b/pyanaconda/ui/tui/simpleline/base.py
> @@ -19,19 +19,47 @@
>  # Red Hat Author(s): Martin Sivak <msivak at redhat.com>
>  #
>  
> -__all__ = ["ExitMainLoop", "App", "UIScreen", "Widget"]
> +__all__ = ["App", "UIScreen", "Widget"]
>  
>  import readline
>  
>  class ExitAllMainLoops(Exception):
> +    """This exceptions ends the whole App mainloop structure. App.run() quits

Should be "exception", singular.

> +       after it is processed."""
>      pass
>  
>  class ExitMainLoop(Exception):
> +    """This eceptions ends the outermost mainloop. Used internally when dialogs

Should be "exception", singular and typo.

> +       close."""
>      pass
>  
>  
>  class App(object):
> +    """This is the main class for TUI screen handling. It is responsible for
> +       mainloop control and keeping track of the screen stack.
> +
> +       Screens are organized in stack structure so it is possible to return
> +       to caller when dialog or sub-screen closes.
> +
> +       It supports four window transitions:
> +       - show new screen replacing the current one (linear progression)
> +       - show new screen keeping the current one in stack (hub & spoke)
> +       - show new screen and wait for it to end (dialog)
> +       - close current window and return to the next one in stack
> +       """
> +
>      def __init__(self, title, yes_or_no_question = None, width = 80):
> +        """
> +        :param title: application title for whenewer we need to display app name

Should be "whenever", typo.

> +        :type title: unicode
> +
> +        :param yes_or_no_question: UIScreen object class used for Quit dialog
> +        :type yes_or_no_question: class UIScreen accepting additional message arg
> +
> +        :param width: screen width for rendering purposes
> +        :type width: int
> +        """
> +
>          self._header = title
>          self._spacer = "\n".join(2*[width*"="])
>          self._width = width
> @@ -40,36 +68,90 @@ class App(object):
>          # screen stack contains triplets
>          #  UIScreen to show
>          #  arguments for it's show method
> -        #  value indicating whether new mainloop is needed - None = do nothing, True = execute, False = already running, exit when window closes
> +        #  value indicating whether new mainloop is needed
> +        #   - None = do nothing
> +        #   - True = execute new loop
> +        #   - False = already running loop, exit when window closes

Now that I read this again, I'd love to see constants defined for these
conditions.

> @@ -100,57 +195,99 @@ class App(object):
>          return input_needed
>  
>      def run(self):
> +        """This methods starts the application. Do not use self.mainloop() directly
> +        as run() handles all the required exceptions needed to keep nested mainloops
> +        working."""
> +
>          try:
>              self.mainloop()
>          except ExitAllMainLoops:
>              pass
>  
>      def mainloop(self):
> +        """Single mainloop. Do not use directly, start the application using run()."""

You could consider renaming it to _mainloop to help reinforce the idea
that it should not be called directly.

- Chris


More information about the anaconda-patches mailing list