jspahrsummers / documentalist Goto Github PK

A multi-language, extensible documentation generator

License: MIT License

Haskell 35.35% C++ 60.56% C 3.78% Shell 0.32%

documentalist's Introduction

Documentalist

Documentalist is an extensible documentation generator that is meant to support multiple source languages, documentation syntaxes, and output formats.

The project includes both a library and executable component:

The library is the main focus of development, and will include most of the logic. The goal is to support embedded documentation generation capabilities in other programs.
The executable is intended to be a simple front-end that automatically hooks up stages for generating pretty documentation output from a chosen source language.

Stages

The architecture is split into three major stages:

A SourceParser locates documentation comments and the declarations to which they're attached. Currently, there's only one SourceParser, built on LibClang.
A CommentParser interprets declarations and comment texts according to a predefined syntax, and creates a language-independent AST. Currently, there's only one CommentParser, which interprets TomDoc style comments.
A Writer generates pretty output, like the final result of Doxygen or Appledoc.

Each stage should depend only on the previous, such that the CommentParser has no knowledge of the source language, and the Writer has no knowledge of the documentation syntax or source language.

Building Concrete Implementations

To make a new implementation for a stage, simply create an instance of the respective typeclass.

If the implementation is meant to be part of Documentalist proper, make sure to follow the existing module structure, and add the new module(s) to the package description.

Getting Started

brew install --with-clang llvm
cabal install --only-dependencies
cabal configure
cabal build

If you want to run the tests:

cabal install --only-dependencies --enable-tests
cabal configure --enable-tests
cabal build
cabal test

documentalist's People

Contributors

Stargazers

Watchers

documentalist's Issues

Make Clang functions pure

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

Variadic arguments

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

Build problems

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.

Tidy parseComment type

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

Configure warning

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.

Appledoc/HeaderDoc-esque Writer

Get dat pretty HTML output.

#imported headers should not be included in the Module

#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.

Travis needs a new repo for llvm-3.4

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 for TomDoc parsing

Tests to see if the TomDoc parser is correct.

Declarations not found outside of the Module and explicit #imports

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.

Pass flags to Clang

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

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.

Swift doc generation

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.

Improve comment marker stripping

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

These methods should never ship in production code.**

Allow any MonadIO for SourceParsers

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.

Separate language and comment parsing

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).

Runtime error

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

Fails to parse. fromJust exception.

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

Use MonadError for SourceParsers

IOException is gross, or so I hear.