From 02b883e6ff4d444e484125129d40edd46fb6b15e Mon Sep 17 00:00:00 2001
From: Timothy Clem <timothy.clem@gmail.com>
Date: Wed, 17 Jan 2018 13:03:23 -0800
Subject: [PATCH] Docs

---
 src/Rendering/Symbol.hs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/Rendering/Symbol.hs b/src/Rendering/Symbol.hs
index d100ec7c3..b59a5fc93 100644
--- a/src/Rendering/Symbol.hs
+++ b/src/Rendering/Symbol.hs
@@ -21,6 +21,10 @@ import Rendering.TOC
 
 
 -- | Render a 'Term' to a ctags like output (See 'Tag').
+--
+-- This format is going away. Prefer the new 'renderToSymbols' as it provides a
+-- more compact data representation and custom field selection. This exists to
+-- back support the staff shipped tag generation in github/github.
 renderToTags :: (HasField fields (Maybe Declaration), HasField fields Span, Foldable f, Functor f) => Blob -> Term f (Record fields) -> [Value]
 renderToTags Blob{..} = fmap toJSON . termToC blobPath
   where
@@ -28,6 +32,7 @@ renderToTags Blob{..} = fmap toJSON . termToC blobPath
     termToC path = mapMaybe (symbolSummary defaultTagSymbolFields path "unchanged") . termTableOfContentsBy declaration
 
 
+-- | Render terms to final JSON structure.
 renderSymbolTerms :: [Value] -> Map.Map T.Text Value
 renderSymbolTerms = Map.singleton "files" . toJSON