0

The objective is to make the docco generated documentation for fluentnode (written in Coffee-Script) as easy to read and understand as possible. At the moment I'm struggling with the best way to represent the function names on the left hand side of the help pages you can access at http://o2platform.com/fluentnode/index.html

At the moment I'm exploring three syntax options:

A) @.{function-name} ({params}) B) {ClassName}::{function-name} ({params}) C) {ClassName}#{function-name} ({params})

As an example, the Array's .empty() method, would be represented as:

A) @.empty ()

B) Array::empty ()

C) Array#empty ()

Note that this would be seen inside the file for a particular class (so it would still be obvious on A that this is related to an array)

To see this in action I used these methodologies on three different help files:

A) @.{function-name} ({params}) on Array.html

image

B) {ClassName}::{function-name} ({params}) on Function.html

image

C) {ClassName}#{function-name} ({params}) on C) http://o2platform.com/fluentnode/Number.html

image

Btw: if there are other ways to represent this, please point me to existing docco generated sites which represent those techniques.

(Question also asked here https://github.com/o2platform/fluentnode/issues/31)

Dinis Cruz
  • 4,161
  • 2
  • 31
  • 49
  • I think this is all opinion but I'll make some comments anyway. **A** seems misleading as you'll rarely say `@push(...)`, you'll almost always say `a.push(...)`; **B** matches the [MDN convention](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) so it makes the most sense to me for CoffeeScript; **C** would be familiar to Ruby people but I don't know about anyone else. – mu is too short Dec 26 '14 at 18:56
  • Yeah, so I originally was using **B** for that reason, but after writing a number of those descriptions, I started to realise that when I needed to mention the actually object being extended it made more sense to use the **@** char since that represents **this** in coffee script (which is the language that all methods are written in ). Which means that when talking about **@.push(..)** the **@** actually represents the object affected by the push. – Dinis Cruz Dec 27 '14 at 00:49
  • Sure, `@` makes sense if that's what you mean but if you're talking about the method then `Class::method` is the only thing that makes sense to me. BTW, be careful with the spaces in your documentation, `f (x, y)` and `f(x, y)` are very different things; if you're going to use parentheses, please use them correctly. – mu is too short Dec 27 '14 at 01:03
  • My problem with the Class::method is that the use of Class is a bit redundant on a page like http://o2platform.com/fluentnode/Function.html , specially when one want to be able to quickly read through the functions and find a particular one. You're right about the extra space on the function call, and I'm worried that that can be a bit problematic (since in Coffee-Script that space makes a difference). I tried using that space to make the function name more readable. – Dinis Cruz Dec 28 '14 at 11:19

1 Answers1

0

I'm going with a variation of option A) which is

@.empty {parmas}

Where I'm not using () in the params which makes it easy to see them

Dinis Cruz
  • 4,161
  • 2
  • 31
  • 49