add documents for the following modules

accounts, audio, langselector, mounts, power, screenedge, screensaver

Change-Id: I389f16af7b6fe37350aca5f6211a562be019bbef

accounts/manager.go

@@ -40,13 +40,16 @@ const (
 )
 
 type Manager struct {
+ // 用户 ObjectPath 列表
  UserList []string
  GuestIcon string
  AllowGuest bool
 
  UserAdded func(string)
  UserDeleted func(string)
  // Error(pid, action, reason)
+ //
+ // 操作失败的信号，参数包括调用者的 pid，被调用的接口和错误信息
  Error func(uint32, string, string)
 
  watcher *dutils.WatchProxy

accounts/manager_ifc.go

@@ -31,6 +31,15 @@ import (
  "time"
 )
 
+// Create new user.
+//
+// 如果收到 Error 信号，则创建失败。
+//
+// name: 用户名
+//
+// fullname: 全名，可以为空
+//
+// ty: 用户类型，0 为普通用户，1 为管理员
 func (m *Manager) CreateUser(dbusMsg dbus.DMessage,
  name, fullname string, ty int32) error {
  pid := dbusMsg.GetSenderPID()
@@ -59,6 +68,11 @@ func (m *Manager) CreateUser(dbusMsg dbus.DMessage,
  return nil
 }
 
+// Delete a exist user.
+//
+// name: 用户名
+//
+// rmFiles: 是否删除用户数据
 func (m *Manager) DeleteUser(dbusMsg dbus.DMessage,
  name string, rmFiles bool) (bool, error) {
  pid := dbusMsg.GetSenderPID()
@@ -106,6 +120,11 @@ func (m *Manager) FindUserByName(name string) (string, error) {
  return m.FindUserById(info.Uid)
 }
 
+// 随机得到一个用户头像
+//
+// ret0：头像路径，为空则表示获取失败
+//
+// ret1: 是否获取成功
 func (m *Manager) RandUserIcon() (string, bool, error) {
  icons := getUserStandardIcons()
  if len(icons) == 0 {
@@ -117,6 +136,13 @@ func (m *Manager) RandUserIcon() (string, bool, error) {
  return icons[idx], true, nil
 }
 
+// 检查用户名是否有效
+//
+// ret0: 是否合法
+//
+// ret1: 不合法原因
+//
+// ret2: 不合法代码
 func (m *Manager) IsUsernameValid(name string) (bool, string, int32) {
  info := checkers.CheckUsernameValid(name)
  if info == nil {

accounts/user.go

@@ -50,7 +50,9 @@ type User struct {
  IconFile string
  BackgroundFile string
 
- Locked bool
+ // 用户是否被禁用
+ Locked bool
+ // 是否允许此用户自动登录
  AutomaticLogin bool
 
  AccountType int32

accounts/user_ifc.go

@@ -315,6 +315,7 @@ func (u *User) IsIconDeletable(icon string) bool {
  return true
 }
 
+// 获取当前头像的大图标
 func (u *User) GetLargeIcon() string {
  baseName := path.Base(u.IconFile)
  dir := path.Dir(u.IconFile)

accounts/utils.go

@@ -39,9 +39,13 @@ const (
 type ErrCodeType int32
 
 const (
+ // 未知错误
  ErrCodeUnkown ErrCodeType = iota
+ // 权限认证失败
  ErrCodeAuthFailed
+ // 执行命令失败
  ErrCodeExecFailed
+ // 传入的参数不合法
  ErrCodeParamInvalid
 )
 

audio/audio.go

@@ -12,12 +12,19 @@ type Audio struct {
  init bool
  core *pulse.Context
 
- Sinks []*Sink
- Sources []*Source
- SinkInputs []*SinkInput
- DefaultSink string
+ // 输出设备 ObjectPath 列表
+ Sinks []*Sink
+ // 输入设备ObjectPath 列表
+ Sources []*Source
+ // 正常输出声音的程序列表
+ SinkInputs []*SinkInput
+
+ // 默认的输出设备名称
+ DefaultSink string
+ // 默认的输入设备名称
  DefaultSource string
 
+ // 最大音量
  MaxUIVolume float64
 
  siEventChan chan func()
@@ -112,20 +119,34 @@ type Sink struct {
  Name string
  Description string
 
+ // 默认音量值
  BaseVolume float64
 
+ // 是否静音
  Mute bool
 
- Volume float64
- Balance float64
+ // 当前音量
+ Volume float64
+ // 左右声道平衡值
+ Balance float64
+ // 是否支持左右声道调整
  SupportBalance bool
- Fade float64
- SupportFade bool
-
- Ports []Port
+ // 前后声道平衡值
+ Fade float64
+ // 是否支持前后声道调整
+ SupportFade bool
+
+ // 支持的输出端口
+ Ports []Port
+ // 当前使用的输出端口
  ActivePort Port
 }
 
+// 设置音量大小
+//
+// v: 音量大小
+//
+// isPlay: 是否播放声音反馈
 func (s *Sink) SetVolume(v float64, isPlay bool) {
  if v == 0 {
  v = 0.001
@@ -135,22 +156,38 @@ func (s *Sink) SetVolume(v float64, isPlay bool) {
  playFeedbackWithDevice(s.Name)
  }
 }
+
+// 设置左右声道平衡值
+//
+// v: 声道平衡值
+//
+// isPlay: 是否播放声音反馈
 func (s *Sink) SetBalance(v float64, isPlay bool) {
  s.core.SetVolume(s.core.Volume.SetBalance(s.core.ChannelMap, v))
  if isPlay {
  playFeedbackWithDevice(s.Name)
  }
 }
+
+// 设置前后声道平衡值
+//
+// v: 声道平衡值
+//
+// isPlay: 是否播放声音反馈
 func (s *Sink) SetFade(v float64) {
  s.core.SetVolume(s.core.Volume.SetFade(s.core.ChannelMap, v))
  playFeedbackWithDevice(s.Name)
 }
+
+// 是否静音
 func (s *Sink) SetMute(v bool) {
  s.core.SetMute(v)
  if !v {
  playFeedbackWithDevice(s.Name)
  }
 }
+
+// 设置此设备的当前使用端口
 func (s *Sink) SetPort(name string) {
  s.core.SetPort(name)
 }
@@ -159,6 +196,7 @@ type SinkInput struct {
  core *pulse.SinkInput
  index uint32
 
+ // process name
  Name string
  Icon string
  Mute bool
@@ -203,6 +241,7 @@ type Source struct {
  Name string
  Description string
 
+ // 默认的输入音量
  BaseVolume float64
 
  Mute bool
@@ -217,6 +256,7 @@ type Source struct {
  ActivePort Port
 }
 
+// 如何反馈输入音量？
 func (s *Source) SetVolume(v float64, isPlay bool) {
  if v == 0 {
  v = 0.001

langselector/locale.go

@@ -42,23 +42,42 @@ const (
 )
 
 const (
- LocaleStateChanged = 0
+ // Locale changed state: has been done
+ //
+ // Locale 更改状态：已经修改完成
+ LocaleStateChanged = 0
+ // Locale changed state: changing
+ //
+ // Locale 更改状态：正在修改中
  LocaleStateChanging = 1
 )
 
 var (
- ErrFileNotExist = fmt.Errorf("File not exist")
- ErrLocaleNotFound = fmt.Errorf("Locale not found")
+ // Error: not found the file
+ //
+ // 错误：没有此文件
+ ErrFileNotExist = fmt.Errorf("File not exist")
+ // Error: not found the locale
+ //
+ // 错误：无效的 Locale
+ ErrLocaleNotFound = fmt.Errorf("Locale not found")
+ // Error: changing locale failure
+ //
+ // 错误：修改 locale 失败
  ErrLocaleChangeFailed = fmt.Errorf("Changing locale failed")
 )
 
 type LangSelector struct {
+ // The current locale
  CurrentLocale string
- Changed func(locale string)
+ // Signal: will be emited if locale changed
+ Changed func(locale string)
 
+ // Store locale changed state
  LocaleState int32
- logger *log.Logger
- lhelper *localehelper.LocaleHelper
+
+ logger *log.Logger
+ lhelper *localehelper.LocaleHelper
 }
 
 type envInfo struct {

langselector/locale_ifc.go

@@ -27,11 +27,19 @@ import (
  . "pkg.linuxdeepin.com/lib/gettext"
 )
 
-type localeInfo struct {
+type LocaleInfo struct {
+ // Locale name
  Locale string
- Desc string
+ // Locale description
+ Desc string
 }
 
+// Set user desktop environment locale, the new locale will work after relogin.
+// (Notice: this locale is only for the current user.)
+//
+// 设置用户会话的 locale，注销后生效，此改变只对当前用户生效。
+//
+// locale: see '/etc/locale.gen'
 func (lang *LangSelector) SetLocale(locale string) error {
  if lang.LocaleState == LocaleStateChanging {
  return nil
@@ -75,7 +83,10 @@ func (lang *LangSelector) SetLocale(locale string) error {
  return nil
 }
 
-func (lang *LangSelector) GetLocaleList() []localeInfo {
+// Get locale info list that deepin supported
+//
+// 得到系统支持的 locale 信息列表
+func (lang *LangSelector) GetLocaleList() []LocaleInfo {
  list, err := getLocaleInfoList(language_info.LanguageListFile)
  if err != nil {
  lang.logger.Warning(err)
@@ -85,15 +96,15 @@ func (lang *LangSelector) GetLocaleList() []localeInfo {
  return list
 }
 
-func getLocaleInfoList(filename string) ([]localeInfo, error) {
+func getLocaleInfoList(filename string) ([]LocaleInfo, error) {
  infoList, err := language_info.GetLanguageInfoList(filename)
  if err != nil {
  return nil, err
  }
 
- var list []localeInfo
+ var list []LocaleInfo
  for _, info := range infoList {
- tmp := localeInfo{info.Locale, info.Description}
+ tmp := LocaleInfo{info.Locale, info.Description}
  list = append(list, tmp)
  }
 

mounts/disk_info.go

@@ -44,17 +44,22 @@ const (
 )
 
 type DiskInfo struct {
+ // Disk description
  Name string
+ // Disk type, ex: native, removable, network...
  Type string
 
  CanUnmount bool
  CanEject bool
 
+ // The size of disk used
  Used uint64
+ // The capacity of disk
  Size uint64
 
- Path string
- UUID string
+ Path string
+ UUID string
+ // The mounted path
  MountPoint string
  Icon string
 }

mounts/manager.go

@@ -46,9 +46,13 @@ type diskObjectInfo struct {
 }
 
 type Manager struct {
+ // All disk info list in system
  DiskList DiskInfos
 
- //Error(uuid, reason)
+ // Error(uuid, reason) signal. It will be emited if operation failure
+ //
+ // uuid: the disk uuid
+ // reason: detail info about the failure
  Error func(string, string)
 
  monitor *gio.VolumeMonitor

mounts/manager_ifc.go

@@ -28,6 +28,9 @@ import (
  "pkg.linuxdeepin.com/lib/gobject-2.0"
 )
 
+// Eject disk.
+//
+// uuid: get from DiskList
 func (m *Manager) DeviceEject(uuid string) (bool, error) {
  value := m.getDiskCache(uuid)
  if value == nil {
@@ -48,6 +51,7 @@ func (m *Manager) DeviceEject(uuid string) (bool, error) {
  return true, nil
 }
 
+// Mount disk.
 func (m *Manager) DeviceMount(uuid string) (bool, error) {
  value := m.getDiskCache(uuid)
  if value == nil {
@@ -68,6 +72,7 @@ func (m *Manager) DeviceMount(uuid string) (bool, error) {
  return true, nil
 }
 
+// Unmount disk.
 func (m *Manager) DeviceUnmount(uuid string) (bool, error) {
  value := m.getDiskCache(uuid)
  if value == nil {