jspahrsummers / documentalist Goto Github PK

Gotta get our game strikethrough on.

It's a bit aggressive right now, stripping off valid Markdown syntax:

These methods should never ship in production code.**

Right now, parsing of the actual source file (via libclang) occurs at the point that newSourceFile is run, which is too early. It shouldn't happen until parse is invoked.

Not sure if this is actually reasonable given the fairly unsafe FFI, but we should look into it.

I'm having trouble building documentalist. I've installed llvm 3.3 through homebrew (keg-only).

Then I ran

cabal install --only-dependencies
cabal configure --extra-include-dirs=/usr/local/opt/lvvm/include --extra-lib-dirs=/usr/local/opt/llvm/lib
cabal build

but I got

Building documentalist-0.1...
Preprocessing library documentalist-0.1...
FFI.hsc:8:10: fatal error: 'clang-c/Index.h' file not found
#include <clang-c/Index.h>
         ^
1 error generated.
compiling dist/build/Text/Documentalist/SourceParser/Clang/FFI_hsc_make.c failed (exit code 1)
command was: /usr/bin/gcc -c dist/build/Text/Documentalist/SourceParser/Clang/FFI_hsc_make.c -o dist/build/Text/Documentalist/SourceParser/Clang/FFI_hsc_make.o -m64 -fno-stack-protector -m64 -D__GLASGOW_HASKELL__=704 -Ddarwin_BUILD_OS=1 -Dx86_64_BUILD_ARCH=1 -Ddarwin_HOST_OS=1 -Dx86_64_HOST_ARCH=1 -I/usr/lib/llvm-3.4/include -I/opt/boxen/homebrew/include -I/usr/local/include -I/usr/local/opt/lvvm/include -std=c99 -Werror -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -I/Library/Frameworks/GHC.framework/Versions/7.4.2-x86_64/usr/lib/ghc-7.4.2/base-4.5.1.0/include -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -I/Library/Frameworks/GHC.framework/Versions/7.4.2-x86_64/usr/lib/ghc-7.4.2/include -Idist/build/autogen -include dist/build/autogen/cabal_macros.h -I/Library/Frameworks/GHC.framework/Versions/7.4.2-x86_64/usr/lib/ghc-7.4.2/include/

it seems to me that it's not passing the include/lib dir to gcc but I'm not sure how to fix that.

IOException is gross, or so I hear.

Change the type of parseComment to not take a Maybe.

Then bring in https://github.com/jspahrsummers/documentalist/pull/25/files#L2R29

parseDecl should be fmap (maybe Nothing parseComment) x

LLVM-3.4 is gone from deb http://llvm.org/apt/precise/ llvm-toolchain-precise main.
It now serves 3.5.

We should use the 3.4rc3 snapshot, or the release when it comes out. To get travis building again.

Tests to see if the TomDoc parser is correct.

This would be really good for Swift. We could do something like Haddock.

I would love to have a Writer that can write to a database for each commit / tag and have a web server serve up the docs.

Filtering out everything that is not public helps people understand the APIs to libraries.

Hopefully, it is just a case of linking the right libraries together.

// Returns a signal which sends 0 and completes.
+ (RACSignal *)zero;

Fails to parse. fromJust exception.

Right now, the Parser module confuses comment extraction with comment-to-IL parsing.

It should be better modularized, so different forms of documentation comments can be interpreted from the same source language (and vice-versa).

#imports are treated like copy-and-paste right now, which means all of the declarations get added to the Module which is supposed to represent one file.

Assumably Clang has some way to exclude imported declarations from the AST.

It's probably sufficient to just treat them as a parameter with the name … and an unknown type.

I think parseDocs though should change from:
parseDocs :: p -> Package (Maybe Comment) -> Either CommentParseException (Package (Maybe DocBlock))
to:
parseDocs :: p -> Package (Maybe Comment) -> Package (Maybe DocBlock)

Because a Package or Module or Declaration can't "fail". Only the Maybe Comment can be unparsable. Then it would be Nothing.

We currently reopen them each time we need a new string from the source, which is horribly inefficient.

Should interpret a language-agnostic version of the TomDoc spec.

When I run cabal configure, I get this output:

Resolving dependencies...
Configuring documentalist-0.1...

/var/folders/6f/5645chpx4n18jth4zwnm6mym0000gn/T/5587.c:1:12:
     warning: control reaches end of non-void function [-Wreturn-type]
int foo() {}
           ^
1 warning generated.

Right now, it assumes -ObjC and nothing else. Command line users should be able to pass through any arbitrary flags.

Many of them do not actually have observable side-effects, and so could become pure at the FFI level or with unsafePerformIO.

Right now, a SourcePackage can only be parsed in IO. We should consider allowing any MonadIO for maximum flexibility in implementation.

Of course, this may make usage more difficult. I don't know whether it's worth it or not.

Get dat pretty HTML output.

This header excerpt:

@class RACStream;

/// A block which accepts a value from a RACStream and returns a new instance
/// of the same stream class.
///
/// Setting `stop` to `YES` will cause the bind to terminate after the returned
/// value. Returning `nil` will result in immediate termination.
typedef RACStream * (^RACStreamBindBlock)(id value, BOOL *stop);

/// An abstract class representing any stream of values.
///
/// This class represents a monad, upon which many stream-based operations can
/// be built.
///
/// When subclassing RACStream, only the methods in the main @interface body need
/// to be overridden.
@interface RACStream : NSObject

results in two documented entries for RACStream:

DecNode (Just 
    # Summary: An abstract class representing any stream of values.
    # Description:
    This class represents a monad, upon which many stream-based operations can
    be built.

    When subclassing RACStream, only the methods in the main @interface body need
    to be overridden.
) `RACStream` (Class []) [],
DecLeaf (Just 
    # Summary: A block which accepts a value from a RACStream and returns a new instance
    of the same stream class.
    # Description:
    Setting `stop` to `YES` will cause the bind to terminate after the returned
    value. Returning `nil` will result in immediate termination.
) `RACStreamBindBlock` (TypeAlias `foobar`),
DecNode (Just 
    # Summary: An abstract class representing any stream of values.
    # Description:
    This class represents a monad, upon which many stream-based operations can
    be built.

    When subclassing RACStream, only the methods in the main @interface body need
    to be overridden.
) `RACStream` (Class []) […]

The second one is the only one with inner declarations, so that's what we should keep.

Standard classes and types, like NSObject and CGRect, are missing.
#32 should really be fixed before this, or else all hell will break loose from importing system headers.