diff options
Diffstat (limited to 'TODO')
| -rw-r--r-- | TODO | 160 |
1 files changed, 0 insertions, 160 deletions
@@ -1,160 +0,0 @@ ------------------------------------------------------------------------------ --- Small improvements - -* When no GHC can be found, give an error message that tells you to use - --with-ghc=<path> - -* Instead of receiving the GHC lib dir as input, try to autodetect it with - ghc --print-libdir. Add a --with-ghc flag instead of -B. - -* Print an error message when given -optghc=.. instead of --optghc=.. - --- --------------------------------------------------------------------------- --- Before next release - -* There should be a --maintainer flag to allow Cabal to pass the maintainer - from the .cabal file to the generated docs. - -* The docs don't mention the module header stuff. - ------------------------------------------------------------------------------ --- bugs - -* parser doesn't support doc comments on types in type aliases: - type MyInt = Int -- ^ comment - -* HsParser bug: starting the module with '-- | doc' followed by a declaration - doesn't parse, because the '-- | doc' is interpreted as the module - documentation (the grammar has an S/R conflict because of this). - -* We don't point module references ("..." in doc strings) to the correct - package, they are always assumed to be modules in the current package. - -* For a non-home occurrence of an entity, we should point to the home - location in the doc somehow. This would help to distinguish - multiple functions with the same name (eg. we don't know whether - Prelude.catch is Control.Exception.catch vs. System.IO.Error.catch). - -* The lexer should handle "...." in doc strings, only recognising it if the - contents looks like a module name. - -* Mentioning a qualified identifer in doc loses the qualifier, even when - it is required? (see "[Haskell] auto-qualification of identifiers in - Haddock"). - -* A module re-export should only reference the target module if the - target module is imported without hiding any of its exports (otherwise - we should inline just the exported bits). - -* Be a bit cleaner about error cases: some internal errors can be - generated by bugs in the Haskell source. Divide out the proper - internal error cases and emit proper error messages. - -* The synopsis generated for a module with no docs should not attempt to - link to the doc for each entity. We need a different kind of summary - here: what we really want is just the documentation section but without - the extra whitespace between decls. - -* We don't handle non-ASCII characters in doc comments. (need to specify - the encoding in the generated HTML too?). - -* There's no way to refer explicitly to either a type/class - constructor or data constructor When there are more than one of - these with the same name. Perhaps introduce a special syntax for - them? (eg. ':C' means data constructor C?) - ------------------------------------------------------------------------------ --- features - - -* Optionally show qualifications of identifiers, that is print -"Sequence.map" rather than "map", "Music.T" rather than just "T". The -option for haddock could be - --qualification QUAL - QUAL=none (default) strip off qualification (just "map") - QUAL=orig show the identifiers as they are written in the module (e.g. "map" or "List.map") - QUAL=full show all identifiers with full qualification (Data.List.map) - Actually I tried to implement it by myself in the old Haddock, but I -could not precisely identify the place, where the qualification is -removed. - -* Documentation of arguments of type constructors other than 'top level' arrows. E.g. - T (a {- ^ arg -} -> b {- ^ result -} ) - (a {- ^ arg -} -> b {- ^ result -} ) -> c - (a {- ^ x coord -}, b {- ^ y coord -}) -> c - It's probably difficult to format properly in HTML. - -* Do something better about re-exported symbols from another package. - -* Haddock could compare interfaces from multiple versions of a module - and indicate changes between versions (eg. a small "new!" or - "changed!" icon, or "stable since 1.0"). - -* Something equivalent to JavaDoc's @since - -* Source code: various people want to get at the source code from the docs. - * Optionally include source code for a function in its docs? - * Suggestion from Benjamin Pierce: generat separate HTML pages with the - source code, with anchors that you can link to from the docs. - Sounds fairly easy to implement... - -* Parse and remember {-# SOURCE #-} imports, possibly do something sensible - with them? - -* nested itemized and enumerated lists. - -* There ought to be a way to include some structure in the "description" - (section headings, etc.) and possibly in other comments. (suggseted - by Daan). - -* Comments on instance declarations? (suggested by Daan and Iavor). - -* Comments on default method declarations? (suggested by Satnam). - -* Comments on components of a tuple, for argument or return types. - -* Add a search feature which just invokes Google? - -* attributes for individual declarations, eg. - -- #abstract - or targetted to a specific decl: - -- #T: abstract - - #long, #short, #noinstances (on a type or class) - - #inline, #noinline on a module export - -* Allow documentation annotations to explicitly name the entity they - refer to. - -* In the contents page, indicate portability/stability of each module - somehow. - -* Add back-references from the definition to the uses of types/classes - (perhaps in the index?) - -* Add a link to the defining location of a re-exported entity - -* fixities - -* include file revision info in module headers - -* Allow individual function arguments to be documented when the function - type is a record element? - -* hiding instances? - -* Add a way to indicate DEPRECATED functions/types/modules? Perhaps - parse the GHC DEPRECATED pragma? - ------------------------------------------------------------------------------ --- cosmetic - -* Allow more parts of the documentation to be squashed and expanded? - -* for a constructor, don't fill its entire cell with a grey background. - -* switch to longer rendering form for datatypes when necessary? - -* remove extra whitespace from the generated HTML to save space - |