Improve some godoc comments

This commit is contained in:
Cameron Moore 2018-09-06 20:40:37 -05:00 committed by Bjørn Erik Pedersen
parent f6f22ad944
commit 30bc4ed0a0
5 changed files with 38 additions and 28 deletions

View file

@ -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}

View file

@ -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
}

View file

@ -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())
}

View file

@ -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),
})
}

View file

@ -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