npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

docs-parser

v0.0.2

Published

Documentation parser, adapts to any language and will help you document all the things.

Downloads

44

Readme

Docs

Docs, addapts to any language and will help you document all the things. Where there is development there is a need for documentation. There are several great libraries for all sorts of files, written by brilliant developers, libraries like SassDoc, JSDoc, JavaDoc, Jazzy, StyleDocco, KSS, Hologram, DSS and several more. All of these libraries do a very good job for documenting their respective languages. However there are very few projects that only require 1 file type. Which means if you really want to document all your code you may have to use 3 or 4 of these documentation generators. Each of the generators have their own way of documenting and their annotations, and their own document site which just makes it harder to keep all your documentation in one spot.

Docs fixes all these issues by giving you the ability to generate documentation for all your files. While giving you control over what annotations you want to use in each file type.

Options

files: file globs to be parsed to get the documentation default

[ 'app/**/*', 'src/**/*', '*.md' ]

ignore: files globs to be ignored default

[
  '.*', // all dot files
  'node_modules/', 'bower_components/', 'jspm_packages/', // package managers
  'dist/', 'build/', 'docs/', // normal folders
  'tests/', 'coverage/' // unit tests and coverage results
]

watch: when true it will watch files for changes default false

raw: Will return the raw data by file, aka data won't be sorted default false

languages: This is an object of comment styles for various languages. default

{
  // annotation identifier that can be change on a file specific basis if needed.
  // While this is a setting, it probably should probably never be changed. If it does
  // need to be changed it should be changed to be a special character.
  prefix: '@',

  // header comment style
  // @note {10} only 1 of these can be used per file
  header: { start: '////', line: '///', end: '////', type: 'header' },

  // body comment style
  body: { start: '', line: '///', end: '', type: 'body' },

  // inline comments for body comments
  inline: { start: '', line: '///#', end: '', type: 'inline' },

  // this is used for any interpolations that might occur in annotations.
  // I don't see this needing to change but just incase I'm making it a setting.
  // @note {10} This setting is used to create a RegExp so certain characters need to be escaped
  interpolation: {
    start: '\\${',
    end: '}'
  },
}

for other predefined languages see the defined languages

Usage

import parser from 'docs-parser'
import fs from 'fs-extra-promisify'

parser({ files: 'app/**/*' })
  .then((data) => fs.outputJson('docs/docs.json', data))

Adding a annotation

documentation for it is coming soon (if your curious just look at src/annotations/*)

Default Annotations

See more on the default annotations

Documenting your items

There are 3 different types of comment blocks block level, and file level.

Note: the comments below are using the comment defaults which are slashes please see defined languages for other language specific comment styles

Header comment

This type of comment can only occur once per file. Any annotations that are found inside of the file level comment will become the default value for the block level comments. It is very useful when you have a whole file sharing some annotations (@author, @page and so on).

////
/// @author Tyler Benton
/// @page functions/numbers
/// @description Useful number functions
////

Body comment block

This type of comment is used multiple times per file.

/// @author Tyler Benton
/// @page functions/numbers
/// @description
/// This function does something awesome, I swear.
@function some-function(){
  // ...
}

Inline comment

This type of comment is used to extend a body comment block

/// @name happypanda
/// @type {object}
const happypanda = {
  smile() { ///# @property {function} happypanda.smile - This makes the panda smile
    return 'smile'
  },
}

Todo

  • Look into adding a callback function that runs after the block has been completely parsed this would be run after the single line comments are parsed. I'm not sure how useful this would be but it's a thought.
    • This could allow you to create your own data structure.
  • Come up with a name for the project
  • Look into being able to reference a different language comment style withing the existing language. For example this would allow you to write JS documentation inside of an HTML document
    <script>
    <!---{js}
     @name something awesome
     @description
     Lorem ipsum dolor sit amet, consectetur adipisicing elit. Vitae praesentium voluptates beatae ducimus dolore velit excepturi maiores delectus doloribus labore totam odio culpa, magni reprehenderit est similique aspernatur dolor rerum?
    ---->
    </script>