Skip to content

Commit

Permalink
More clean up.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ryanfitzer
ryanfitzer committed Jun 9, 2016
1 parent 56c1de0 commit 722a710
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 155 deletions.
18 changes: 11 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,15 +109,19 @@ Custom tag parsers can be passed to the `options` argument. See `lib/parsers.js`

## Syntax Support ##

Comment delimiters:

```
/** <- commentBegin
* <- commentLinePrefix
* @tag <- tagPrefix (the "@" symbol)
*/ <- commentEnd
```

While most documentation comment styles should be supported, there are a few rules around the syntax:

1. The `commentBegin`, `commentLinePrefix`, `commentEnd` and `tagPrefix` delimiter tokens are distinct from each other.

/** <- commentBegin
* <- commentLinePrefix
* @tag <- tagPrefix (the "@" symbol)
*/ <- commentEnd


2. Delimiters should not rely on a whitespace character. For example, the following style would not be supported:

/**
Expand All @@ -126,7 +130,7 @@ While most documentation comment styles should be supported, there are a few rul
@tag
*/

3.
3. ?????



Expand Down
172 changes: 24 additions & 148 deletions index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,73 +27,21 @@ function factory( config ) {
var safeCommentEnd = patterns.commentEnd.replace( rCharacterClasses, lastMatch );

var rLeadSpaces = /^[^\S\n]*/;
// var rTestCommentBegin = new RegExp( `${safeCommentBegin}\\s*\\n\\s*${safeCommentLinePrefix}` );
var rCommentPreface = new RegExp( `.*${safeTagPrefix}(.+)\\s` );
// var rCommentLinePrefix = new RegExp( `^(\\s)*${safeCommentLinePrefix}\\s?` );
var rComment = new RegExp( `(${safeCommentBegin}\\s*\\n\\s*${safeCommentLinePrefix}(?:.|\\n)*?${safeCommentEnd}\\s*\\n?)` );
var rCommentLinePrefix = new RegExp( `^(\\s)*${safeCommentLinePrefix}` );
var rCommentLinePrefixGM = new RegExp( `^\\s*${safeCommentLinePrefix}`, 'gm' );
var rTagName = new RegExp( `^${safeTagPrefix}([\\w-])+` );
var rComment = new RegExp( `(${safeCommentBegin}\\s*\\n\\s*${safeCommentLinePrefix}(?:.|\\n)*?${safeCommentEnd}\\s*\\n?)` );
var parsers = options.parsers || {};

/**
* Splits a string into an array of sections.
* The array has 3 parts:
* - starting line number
* - comment block stripped of `commentBegin`, `commentEnd` and
* `commentLinePrefix` tokens, including leading spaces between
* the `commentLinePrefix` and the `tagPrefix` tokens.
* - all source between the `commentEnd` token and next `commentBegin` token.
* Splits a string into array of sections. Each section 3 properties:
*
* - line: starting line number
* - source: the comment source
* - context: source between the `commentEnd` token and next `commentBegin` token (or EOF).
*
* @param sourceStr {String} The source to parse.
* @return {Array}
*/
/*
function explodeSections( sourceStr ) {
var sections = sourceStr.split( rTestCommentBegin )
// Add an extra line to make up for the `commentBegin` line that gets removed during split
var startLineNumber = getLinesLength( sections.shift() ) + 1;
return sections.reduce( function( collection, section ) {
var splitSection = section.split( patterns.commentEnd );
var nextLine = startLineNumber + section.split( '\n' ).length;
// Since multiple `commentEnd` tokens could be present in
// a section, we need to manually split section into two parts
section = [
splitSection[ 0 ],
splitSection.slice( 1 ).join( patterns.commentEnd )
];
section = section.map( function( block, sectionIndex ) {
block = block.split( '\n' ).map( function( line ) {
// Only strip `rCommentLinePrefix` if it's part of the comment block section
if ( !sectionIndex ) {
return line.replace( rCommentLinePrefix, '' );
}
return line;
}).join( '\n' );
return block;
});
section.unshift( startLineNumber );
startLineNumber = nextLine;
collection.push( section );
return collection;
}, [] );
}
*/
function explodeSections( sourceStr ) {

var sections = sourceStr.split( rComment );
Expand All @@ -116,51 +64,21 @@ function factory( config ) {
prevSectionLineLength += getLinesLength( section );

return accum;

}, [] );

/*
return sections.reduce( function( collection, section ) {
var splitSection = section.split( patterns.commentEnd );
var nextLine = startLineNumber + section.split( '\n' ).length;
// Since multiple `commentEnd` tokens could be present in
// a section, we need to manually split section into two parts
section = [
splitSection[ 0 ],
splitSection.slice( 1 ).join( patterns.commentEnd )
];
section = section.map( function( block, sectionIndex ) {
block = block.split( '\n' ).map( function( line ) {
// Only strip `rCommentLinePrefix` if it's part of the comment block section
if ( !sectionIndex ) {
return line.replace( rCommentLinePrefix, '' );
}
return line;
}).join( '\n' );
return block;
});
section.unshift( startLineNumber );
startLineNumber = nextLine;
collection.push( section );
return collection;
}, [] );
*/


}


/**
* Strip and serialize a comment into its various parts.
*
* - comment: the comment block stripped delimiters and leading spaces.
* - preface
* - tags
*
* @param lineNumber {Number} The comment's starting line number.
* @param section {String} The comment's source.
* @return {Object}
*/
function stripAndSerializeComment( lineNumber, sourceStr ) {

// Strip comment delimiter tokens
Expand All @@ -170,7 +88,7 @@ function factory( config ) {
.split( '\n' )
.map( line => line.replace( rCommentLinePrefix, '' ) );

// Determine the number of preceeding spaces to strip
// Determine the number of leading spaces to strip
var prefixSpaces = stripped.reduce( function( accum, line ) {

if ( !accum.length && line.match( /\s*\S|\n/ ) ) {
Expand All @@ -180,7 +98,7 @@ function factory( config ) {
return accum;
});

// Strip preceeding spaces
// Strip leading spaces
stripped = stripped.map( line => line.replace( prefixSpaces, '' ) );

// Get line number for first tag
Expand All @@ -205,39 +123,6 @@ function factory( config ) {
}
}

/**
* Serialize a section into its various parts.
* - line
* - preface
* - tags
* - context
* - source
*
* @param lineNumber {Number} The comment's starting line number.
* @param section {String} The comment and its contextual source.
* @return {Object}
*/
/*
function serializeBlock( section ) {
var lineNumber = section[ 0 ]
, source = section[ 1 ]
, context = section[ 2 ].trim()
, preface = source.split( rCommentPreface )[ 0 ].trim()
, tags = source.replace( preface, '' ).trim()
, startingIndex = lineNumber + getLinesLength( source.split( rCommentPreface )[ 0 ] ) + 1
;
return {
line: lineNumber,
preface: preface,
tags: serializeTags( startingIndex, tags ),
context: context,
source: source
};
}
*/

/**
* Takes a tags block and serializes it into individual tag objects.
*
Expand All @@ -263,7 +148,6 @@ function factory( config ) {
.map( function( block ) {

var trimmed = block.trim()
// , tag = trimmed.match( rTagName )[0]
, tag = block.match( rTagName )[0]
;

Expand All @@ -287,7 +171,6 @@ function factory( config ) {

try {

// Tag = Object.assign( tag, parser( tag.value ) );
tag.valueParsed = parser( tag.value );
}
catch ( err ) {
Expand All @@ -301,7 +184,10 @@ function factory( config ) {
}

/**
*
* Get the number of newlines in a block of text.
*
* @param text {String}
* @return {Number}
*/
function getLinesLength( text ) {

Expand All @@ -310,9 +196,6 @@ function factory( config ) {
return matches ? matches.length : 0;
}

/**
*
*/
return function( src ) {

return explodeSections( src ).map( function ( section ) {
Expand All @@ -326,12 +209,5 @@ function factory( config ) {
console.log( util.inspect( section, { depth: 5, colors: true } ) );
return section;
});

// return sections.reduce( function( collection, section ) {
//
// collection.push( serializeBlock( section ) );
//
// return collection;
// }, [] );
};
}

0 comments on commit 722a710

Please sign in to comment.