Improve some godoc comments

diff --git a/hugofs/basepath_real_filename_fs.go b/hugofs/basepath_real_filename_fs.go
index d419c4ea34883e9c5ad54c758115a8ac72bffb12..1024c4d3034b54d8031211c1c9aabb4b909d1396 100644 (file)
--- a/hugofs/basepath_real_filename_fs.go
+++ b/hugofs/basepath_real_filename_fs.go
@@ -36,7 +36,7 @@ func (f *realFilenameInfo) RealFilename() string {
        return f.realFilename
 }
 
-// NewBasePathRealFilenameFs returns a new NewBasePathRealFilenameFs instance
+// NewBasePathRealFilenameFs returns a new BasePathRealFilenameFs instance
 // using base.
 func NewBasePathRealFilenameFs(base *afero.BasePathFs) *BasePathRealFilenameFs {
        return &BasePathRealFilenameFs{BasePathFs: base}

diff --git a/hugofs/language_fs.go b/hugofs/language_fs.go
index ce331fca4940af93eb6e9861675591c74849aeb6..db77c1fabd395e467a9d5506a8e2c918be3243c2 100644 (file)
--- a/hugofs/language_fs.go
+++ b/hugofs/language_fs.go
@@ -51,7 +51,8 @@ type FilePather interface {
        BaseDir() string
 }
 
-// LanguageDirsMerger implements the afero.DirsMerger interface.
+// LanguageDirsMerger implements the afero.DirsMerger interface, which is used
+// to merge two directories.
 var LanguageDirsMerger = func(lofi, bofi []os.FileInfo) ([]os.FileInfo, error) {
        m := make(map[string]*LanguageFileInfo)
 
@@ -102,39 +103,41 @@ type LanguageFileInfo struct {
        weight int
 }
 
-// Filename returns a file's real filename.
+// Filename returns a file's real filename including the base (ie.
+// "/my/base/sect/page.md").
 func (fi *LanguageFileInfo) Filename() string {
        return fi.realFilename
 }
 
-// Path returns a file's relative filename.
+// Path returns a file's filename relative to the base (ie. "sect/page.md").
 func (fi *LanguageFileInfo) Path() string {
        return fi.relFilename
 }
 
-// RealName returns a file's real name.
+// RealName returns a file's real base name (ie. "page.md").
 func (fi *LanguageFileInfo) RealName() string {
        return fi.realName
 }
 
-// BaseDir returns a file's base directory.
+// BaseDir returns a file's base directory (ie. "/my/base").
 func (fi *LanguageFileInfo) BaseDir() string {
        return fi.baseDir
 }
 
-// Lang returns a file's language.
+// Lang returns a file's language (ie. "sv").
 func (fi *LanguageFileInfo) Lang() string {
        return fi.lang
 }
 
 // TranslationBaseName returns the base filename without any extension or language
-// identificator.
+// identifiers (ie. "page").
 func (fi *LanguageFileInfo) TranslationBaseName() string {
        return fi.translationBaseName
 }
 
 // Name is the name of the file within this filesystem without any path info.
-// It will be marked with language information so we can identify it as ours.
+// It will be marked with language information so we can identify it as ours
+// (ie. "__hugofs_sv_page.md").
 func (fi *LanguageFileInfo) Name() string {
        return fi.name
 }
@@ -175,7 +178,7 @@ type LanguageFs struct {
        afero.Fs
 }
 
-// NewLanguageFs creates a new LanguageFs.
+// NewLanguageFs creates a new language filesystem.
 func NewLanguageFs(lang string, languages map[string]bool, fs afero.Fs) *LanguageFs {
        if lang == "" {
                panic("no lang set for the language fs")
@@ -191,7 +194,7 @@ func NewLanguageFs(lang string, languages map[string]bool, fs afero.Fs) *Languag
        return &LanguageFs{lang: lang, languages: languages, basePath: basePath, Fs: fs, nameMarker: marker}
 }
 
-// Lang returns a language filesystem's language.
+// Lang returns a language filesystem's language (ie. "sv").
 func (fs *LanguageFs) Lang() string {
        return fs.lang
 }

diff --git a/hugofs/language_fs_test.go b/hugofs/language_fs_test.go
index 060f59448368c16c34cedfeb27a09791ea30ea76..c86d5158c00d57fbf5a01401ccb3e89a47a0360e 100644 (file)
--- a/hugofs/language_fs_test.go
+++ b/hugofs/language_fs_test.go
@@ -50,6 +50,9 @@ func TestLanguagFs(t *testing.T) {
        assert.Equal("page.sv.md", lfi.virtualName)
        assert.Equal("__hugofs_sv_page.md", lfi.Name())
        assert.Equal("page.md", lfi.RealName())
+       assert.Equal("/my/base", lfi.BaseDir())
+       assert.Equal("sv", lfi.Lang())
+       assert.Equal("page", lfi.TranslationBaseName())
 
 }
 

diff --git a/output/outputFormat.go b/output/outputFormat.go
index ec1838b3944c221f965de2a3b646d94b522204b8..9b1f838546a762cab2712b2bf88b5a5a6824f118 100644 (file)
--- a/output/outputFormat.go
+++ b/output/outputFormat.go
@@ -331,19 +331,20 @@ func decode(mediaTypes media.Types, input, output interface{}) error {
        return decoder.Decode(input)
 }
 
-// BaseFilename returns the base filename of formats.
-func (formats Format) BaseFilename() string {
-       return formats.BaseName + formats.MediaType.FullSuffix()
+// BaseFilename returns the base filename of f including an extension (ie.
+// "index.xml").
+func (f Format) BaseFilename() string {
+       return f.BaseName + f.MediaType.FullSuffix()
 }
 
-// MarshalJSON returns the JSON encoding of formats.
-func (formats Format) MarshalJSON() ([]byte, error) {
+// MarshalJSON returns the JSON encoding of f.
+func (f Format) MarshalJSON() ([]byte, error) {
        type Alias Format
        return json.Marshal(&struct {
                MediaType string
                Alias
        }{
-               MediaType: formats.MediaType.String(),
-               Alias:     (Alias)(formats),
+               MediaType: f.MediaType.String(),
+               Alias:     (Alias)(f),
        })
 }

diff --git a/source/fileInfo.go b/source/fileInfo.go
index 7510f306e282555b30e99213610945999f49c8db..fc55706fe0fe8086991203169df5622e1c00b7d3 100644 (file)
--- a/source/fileInfo.go
+++ b/source/fileInfo.go
@@ -114,31 +114,34 @@ type FileInfo struct {
        lazyInit sync.Once
 }
 
-// Filename returns a file's filename.
+// Filename returns a file's absolute path and filename on disk.
 func (fi *FileInfo) Filename() string { return fi.filename }
 
-// Path returns a file's relative path.
+// Path gets the relative path including file name and extension.  The directory
+// is relative to the content root.
 func (fi *FileInfo) Path() string { return fi.relPath }
 
-// Dir returns a file's directory.
+// Dir gets the name of the directory that contains this file.  The directory is
+// relative to the content root.
 func (fi *FileInfo) Dir() string { return fi.relDir }
 
-// Extension returns a file's extension.
+// Extension is an alias to Ext().
 func (fi *FileInfo) Extension() string { return fi.Ext() }
 
-// Ext returns a file's extension without the leading period.
+// Ext returns a file's extension without the leading period (ie. "md").
 func (fi *FileInfo) Ext() string { return fi.ext }
 
-// Lang returns a file's language.
+// Lang returns a file's language (ie. "sv").
 func (fi *FileInfo) Lang() string { return fi.lang }
 
-// LogicalName returns a file's name.
+// LogicalName returns a file's name and extension (ie. "page.sv.md").
 func (fi *FileInfo) LogicalName() string { return fi.name }
 
-// BaseFileName returns a file's base name.
+// BaseFileName returns a file's name without extension (ie. "page.sv").
 func (fi *FileInfo) BaseFileName() string { return fi.baseName }
 
-// TranslationBaseName returns a file's translation base name.
+// TranslationBaseName returns a file's translation base name without the
+// language segement (ie. "page").
 func (fi *FileInfo) TranslationBaseName() string { return fi.translationBaseName }
 
 // Section returns a file's section.
@@ -147,7 +150,7 @@ func (fi *FileInfo) Section() string {
        return fi.section
 }
 
-// UniqueID returns a file's unique identifier.
+// UniqueID returns a file's unique, MD5 hash identifier.
 func (fi *FileInfo) UniqueID() string {
        fi.init()
        return fi.uniqueID